When we talk about open source repositories, there can be a lot of moving pieces, especially for maintainers. We’re juggling new issues, duplicate issues, discussions, pull requests, and many of us are volunteers. Although there will always be new challenges, between some simple things maintainers can do to make their repositories more contributor-friendly, and some tools that GitHub provides to help maintainers, we can reduce barriers to entry and reduce friction as we continue open-source projects. Here’s a list to help get you started.
Maintainer Checklist
If you’re interested in some of the things maintainers can do to create a positive space for contributions, check out the OSS Maintainer Guide created at Virtual Coffee.
The guide covers important things like documentation, Code of Conduct, the Contributing Guide, and how to make your repository welcoming to new contributors.
One of the most important parts of any open source project is to have clear paths of communication. Detailed instructions of how to communicate with maintainers, instructions for creating or working on issues, and when to create a pull request, should be covered in your Contributors Guide. For an example, you can check out our Contributors Guide.
Issues
One of the ways to help contributors and yourself as a maintainer is to utilize issue templates or forms. For a detailed guide on how to do this with your GithHub repository, you can check out their doc Configuring issue templates for your repository . (And a quick note to say that forms are in beta right now, so keep that in mind. Personally, I think they’re pretty awesome so I’d love to see them stick around.)
If you don’t have issues set up, and a contributor wants to add an issue, there’s really no guidance on how to do it. Not only is the contributor left staring at a blank box, but the likelihood of getting all of the information you need as a maintainer to make a decision about the issue isn’t great as well.
But including forms or templates in your repository can eliminate some of those clarifying conversations. And one of the cool things is, you can create different templates/forms depending on your needs.
You can give a more detailed breakdown of what information you want to see when you read the issue.
If you want to take a look at how we breakdown our issues, you can check each of them out:
Within that list, we also have Questions/Ideas/Feedback, which takes our contributors to our discussion board where we like to start the conversation before converting it to an issue as we see fit–which I think deserves a post of its own.
Labels
Make labels your friend. This makes it easy for contributors to quickly scan or to sort the issues on your repository and it makes it easier for you to separate and breakdown possible features, bug fixes, status of issues, etc.
Remember, let the labels work for you. Not only can you create the labels and choose the color of the label, but you can also add a description for what that label means. This makes it easier for your contributors to understand as well.
The goal for everything you do for your repository is to create clear paths of communication.
And you might not get it right every time. In fact, you might try something that you think is great, only to discover that it’s made things more complicated. That’s fine! You tried it, and now you can remove it, edit it, update it, do what works for your project right now. And that’s a good mindset to have. We should always be evaluating and re-evaluating our processes, projects, and ourselves to make sure we’re updating things that need updated and growing.