What makes a good beginner open source issue?
In the days leading up to codebar’s 24 Pull Requests event, we asked the community to submit good, beginner-friendly issues they found on Github for our students to work on during the event. Our 24 Pull Requests themed event is a day of helping beginner coders get started in contributing to open source software. The most common question we got was what constitutes a good beginner open source issue? The question is valid, especially from the perspective of a seasoned developer who can easily make sense of developer jargon and can understand other developers’ intentions from a few brief sentences. That isn’t the case for a complete beginner. As someone who was once a beginner — some would say still is — I think I can give some tips on what kind of issues helped me get started with open source and what kind of issues might suit other beginners.
Small bugs, or very small features
As a beginner it is important to start with small, succinct tasks. Things that can be solved in a day or better, an hour. Remember, when you are a beginner, contributing to open source isn’t only about fixing the bug but everything else that comes with the process: forking the repo, cloning it, setting it up, finding the bug, fixing it, adding, committing, pushing, opening the PR and so on. This might mean relinquishing some control of your project and offering up quick fixes and small features to potential contributors. Yes, you might be able to fix that small bug in two seconds yourself and never think about it again, but for a beginner that two second bug might be the issue that sets them off on a journey of contributing to open source.
Issues with a clear context
Projects with a setup guide
Not once have I found an issue on Github I deemed solvable with my limited skills only to find out the project has no setup instructions. As I mentioned in the first point, setting up the project itself is one of the most daunting parts of starting to contribute to open source. I have personally abandoned several projects because I got stuck whilst setting up the local dev environment and found the effort of reaching out to the maintainer or figuring it out on my own too much compared to the relatively easy task of solving a simple issue. If you want people to contribute to your project please take the time to write clear and detailed setup instructions.
Responsive project maintainers
It can be extremely discouraging to finally open that first PR you’ve worked so hard on, to then not hear from the maintainer for weeks, sometimes even months. We at codebar are guilty of this too. It is hard to always be up to date on a project from a maintainers point of view, but it is extremely important for a beginner to get prompt feedback on their PR. Don’t be afraid to give feedback either. If you don’t like the design they did for example, or want them to refactor some code, let them know in a respectful and objective way. The key is clear and respectful communication and collaboration.
It’s not only about code
This has been said many times but code is not the only way to contribute to an open source project. Think about all the other components that make up a project: documentation, visual design, UX, user testing, accessibility, etc. These are all components of your project that you can open up to the community. But don’t over do it either. I’ve seen many, many issues that simply stated ‘write documentation for xy’. How would a beginner, who relies on documentation more than anything, know where to start with it? Provide a rough draft of the documentation and ask people to contribute to that.
All of this means that project maintainers have to put in the time to create issues that are clear and understandable. It means they have to aid and help out beginners to contribute to open source projects. This may mean holding someone’s hand in fixing their first issue and submitting their first PR on the project. Yes, this takes time and effort, but it’s the only way to build a community of willing participants around a project and to get more people involved in open source.
Originally published at blog.codebar.io on November 20, 2015.