Open source software is produced by communities of people collaborating on projects, and you are invited to join the conversation. The Open Source Guide to Community and Project Management is a guide to help open source contributors who want to create a successful and stable project.
This guide is a collection of tips and tricks to keep your open source project fresh and up-to-date. I’ve worked on a number of successful projects, both small and large, in areas such as software, hardware, and semiconductor design. In this work, I’ve learned some painful lessons relating to version control and bug-tracking systems. Here are the top three things you need to know to successfully manage an open source project.
Issues are typically a way to keep track of or report bugs, or to request new features to be added to the code base. Open-source repository hosting services like GitHub, GitLab, and Bitbucket will provide you with an interface for yourself and others to keep track of issues within your repository. When releasing open-source code to the public, you should expect to have issues opened by the community of users. Organizing and prioritizing issues will give you a good road map of upcoming work on your project.
Because any user can file an issue, not all issues will be reporting bugs or be feature requests; you may receive questions via the issue tracker tool, or you may receive requests for smaller enhancements to the user interface, for example. It is best to organize these issues as much as possible and to be communicative to the users who are creating these issues.
Issues should represent concrete tasks that need to be done on the source code, and you will need to prioritize them accordingly. You and your team will have an understanding of the amount of time and energy you or contributors can devote to filed issues, and together you can work collaboratively to make decisions and create an actionable plan. When you know you won’t be able to get to a particular issue within a quick timeframe, you can still comment on the issue to let the user know that you have read the issue and that you’ll get to it when you can, and if you are able to you can provide an expected timeline for when you can review the issue again.
For issues that are feature requests or enhancements, you can ask the person who filed the issue whether they are able to contribute code themselves. You can direct them to the
CONTRIBUTORS.md file and any other relevant documentation.
Since questions often do not represent concrete tasks, commenting on the issue to courteously direct the user to relevant documentation can be a good option to keep your interactions professional and kind. If documentation for this question does not exist, now is a great time to add the relevant documentation, and express your thanks to the user for identifying this oversight. If you are getting a lot of questions via issues, you may consider creating a FAQ section of your documentation, or a wiki or forum for others to participate in question-answering.
Whenever a user reports an issue, try to be as kind and gracious as possible. Issues are indicators that users like your software and want to make it better!
Working to organize issues as best you can keep your project up to date and relevant to its community of users. Remove issues that are outside of the scope of your project or become stale, and prioritize the others so that you are able to make continuous progress.
Communicate your expectations
Rules can be nerve-wracking to write down. Sometimes you might feel like you’re policing other people’s behavior or killing all the fun.
Written and enforced fairly, however, good rules empower maintainers. They prevent you from getting dragged into doing things you don’t want to do.
Most people who come across your project don’t know anything about you or your circumstances. They may assume you get paid to work on it, especially if it’s something they regularly use and depend on. Maybe at one point you put a lot of time into your project, but now you’re busy with a new job or family member.
All of this is perfectly okay! Just make sure other people know about it.
If maintaining your project is part-time or purely volunteered, be honest about how much time you have. This is not the same as how much time you think the project requires, or how much time others want you to spend.
Here are a few rules that are worth writing down:
- How a contribution is reviewed and accepted (Do they need tests? An issue template?)
- The types of contributions you’ll accept (Do you only want help with a certain part of your code?)
- When it’s appropriate to follow up (for example, “You can expect a response from a maintainer within 7 days. If you haven’t heard anything by then, feel free to ping the thread.”)
- How much time you spend on the project (for example, “We only spend about 5 hours per week on this project”)
This is absolutely critical if you want anyone to contribute to your project.
Nobody is going to bother with your project if you don’t even have a README.
Think about it. When you look at other people’s projects, what’s the first thing you look for? You look for written information, right? Anything that tells you what you’re looking at, what it’s for, how to use it.
Make it easy for people to find the information they want. A good README goes a really long way.
Whenever I need some inspiration, I scroll through the Awesome README repo. Definitely check it out for some fantastic content and layout ideas.
Finally, go to your GitHub repo, click on the “Insights” tab, and click on the “Community” tab.
This shows a list of common documentation you should have. The more of these things that you have, the friendlier your project will appear to potential contributors.
Including these pieces will make it easier for people to start contributing. It will also lay out the ground rules to help you maintain a productive and positive community. Nobody wants to be in a toxic environment.
Caring for an open source project is a lot like caring for a garden. You must regularly attend to it, nourish it, and watch out for weeds. This book is intended to be a guide to help you grow your garden in such a way that everyone can enjoy the fruits of your labor.