What makes a good beginner open source issue?

In the days leading up to our 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 make sense of very specific 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

We’ve all seen issues on Github with a non-descriptive title like ‘remove no-js tags with js’. No description, no context. This in principal sounds like something a beginner with very little Javascript knowledge could do. Right. Detect whether an element has a no-js class and consequently remove it. But the lack of context makes it almost impossible to understand what the actual issue is and what is expected of the contributor. A good beginner issue has a clear description and gives as much guidance as possible without actually solving the issue. You are a project maintainer and might have an idea where in the project the bug might lie? Good, include the partial you think the bug might be coming from. You have a visual representation of the issue? Great, include a screenshot of it. The more details you include the better.

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.