How to use Github issues to attract new contributors

Many open source projects need new contributors but struggle to find them. Conversely, many first time contributors have problems finding what to work on. What’s the problem? As programmers, we focus most of our attention to the code, forgetting about the community work that needs to be done to make it accessible.

For many projects, the list of issues on Github is the main point of contact between users and developers. People will come to the issue tracker with different purposes and levels of familiarity with your application, reporting bugs, requesting features, asking questions and looking to contribute. How to make sure that they find what they need?

Use good labels

Labels are the way to organise issues on Github. You can assign a name and colour to every one and that’s it. Pretty straight-forward and flexible; you can capture practically anything with them.

However, there’s a fine line between using labels well and overusing them. When there’s too many or the system is too complex, people will just ignore them. So what is worth making a label for?

Type of work

Is it an entirely new feature, small enhancement to an existing one or bugfix? Maybe the documentation needs fixing or the home page could use a fresh look.

Not all tasks require programming and not all contributors to your project need to be programmers. Tagging issues to separate coding from other tasks, such as design and docs, can help you attract tech writers and designers that are excited about open source or enthusiastic users of your project. Here’s an example:

• Design
• Docs
• Code

If your project doesn’t have documentation (good time to create an issue) or it’s a terminal app without a homepage or anything that would require a designer, you can split Code into several categories to let people know what they’re getting into. For example:

• Bugfix
• Enhancement
• New feature
• Refactoring
• Tests

Needless to say, these will overlap. Every task is an enhancement in a way and you will need to write some tests when adding new features. If the task is bigger or more ambiguous, resist the temptation to assign all the labels to it. Instead, try breaking it down or choose the one that’s most appropriate. If you still don’t know, let it to atmospheric noise to decide. Striving for complete accuracy often leads to even less organisation due to the difficulty of maintaining it.

Difficulty

Estimating the difficulty of each issue is particularly useful for newcomers to your project. I use the following three levels:

• Beginner
• Intermediate
• Bigger project

This will make sure people who just arrived won’t be trying to solve things you yourself are afraid to tackle. Using the filters on Github, you’ll be able to link directly to a list of issues suitable for beginners from your README. Like this.

Priority and severity

While these two are probably the most common ways of categorising software tickets, I’m not sure how useful they are for open source projects. For companies, these can be used to prioritise employee’s time and make sure problems critical for the business are tackled first.

With open source projects though, people just work on what they want to work on. Different people will see these very differently based on how they use the app and what’s important to them.

Also, marking issues low priority and trivial severity isn’t very encouraging for people to start working on them. These are exactly the type of issues you want newcomers to be tackling first, so they get up to speed with the project and marking the work inconsequential is wrong. The goal of a trivial, low priority issue is to get a new contributor onboard. That’s bloody high priority to me…

If you really need a way of marking important issues, use just a single Critical label.

Explain it in the README

Don’t forget to write a few words about the way the issues are structured in your project’s README. It doesn’t have to be a three-page long treatise on the subject. In fact, the shorter you can get it the better your system probably is.

Make sure to mention the categories of tags you’re using and include links to the filtered lists of each category, particularly the ones aimed at beginners.

Summary

The issue tracker is one of the places where your contributors hang out. For some projects, it may be the only place. Maintaining it with the same standards as you would maintain the code will help you build a great community.

After all, the tickets aren’t there for the project itself, but for the people who make it.