A project is maintained with the help of developers, UX designers, and marketing experts. Each member of the team holds responsibility for a certain part of the application development process. The main idea is to develop a framework or platform where users can get the information they need.
This guide is intended to help new project maintainers make the transition from newcomer to experienced maintainer. It’s a collection of the things that I wish I’d known when I first became a project maintainer. Since then, I’ve helped hundreds of new project maintainers and collected their advice, and this guide has evolved over a number of years into what it is today.
Write Useful Documentation
Documentation that is thorough, well-organized, and serves the intended communities of your project will help expand your user base. Over time, your user base will become the contributors to your open-source project.
Since you’ll be thinking through the code you are creating anyway, and may even be jotting down notes, it can be worthwhile to incorporate documentation as part of your development process while it is fresh in your mind. You may even want to consider writing the documentation before the code, following the philosophy of a documentation-driven development approach that documents features first and develops those features after writing out what they will do.
Along with your code, there are a few files of documentation that you’ll want to keep in your top-level directory:
README.mdfile that provides a summary of the project and your goals.
CONTRIBUTING.mdfile with contribution instructions.
- License for your software, which can encourage more contributions. Read more about choosing an open-source license here.
Documentation can come in many forms and can target different audiences. As part of your documentation, and depending on the scope of your work, you may decide to do one or more of the following:
- A general guide to introduce users to the project
- Tutorials to walk people through different use cases
- FAQs to address frequently asked questions that users may have
- Troubleshooting guides to help users resolve problems
- An API reference provides users with a quick way to find API information
- Release notes with known bugs to let users know what to expect in each release
- Planned features to keep track of and explain what is coming up in the future
- Video walkthroughs to provide users with a multimedia approach to your software
Good communication skills keep your community happy
Seriously. Open lines of communication help keep things clear. Clarity makes it easier for users and contributors to get the information from the documentation, lowering the number of redundant questions.
Although it can sometimes be irritating if a user asks a question that is clearly covered in the documentation, keep your cool and strive to be helpful. Keep zen and point them in the right direction. Sure, being a little curt is easier, but it’s hard to win friends and influence people if you’re being a dick.
Instead, try to remember that you’re building a community here and that you too started out as a beginner. Be kind, be helpful, and be informative.
This is especially true in cases where you need to say no. As the Open Source Guide points out, “Saying no isn’t fun, but “Your contribution doesn’t match this project’s criteria” feels less personal than “I don’t like your contribution”.
Practice a kind but firm no for suggestions you’re not crazy about in the issues and pull requests, derailed discussions, and requests for more unnecessary work. This is where clear guidelines and rules come in handy!
Choose a license
This is easy to overlook. You might think, who cares? My project is small, and I don’t care what people do with my code.
Well, a license doesn’t just protect you or your project.
It gives people confidence in using and/or contributing to your project.
I’ve seen people online say that if your project doesn’t have a license, they won’t contribute to it or use your code in any of their work.
If the rules aren’t clear, why risk getting involved?
Write down your project’s vision
Start by writing down the goals of your project. Add them to your README, or create a separate file called VISION. If there are other artifacts that could help, like a project roadmap, make those public as well.
Having a clear, documented vision keeps you focused and helps you avoid “scope creep” from others’ contributions.
For example, @lord discovered that having a project vision helped him figure out which requests to spend time on. As a new maintainer, he regretted not sticking to his project’s scope when he got his first feature request for Slate.
Helping Others Contribute
Whether or not you expect anyone to contribute to your project, you should be prepared for the possibility of others wanting to help your cause. And when that happens, your contributing guide will show those helpers exactly how they can get involved. This guide, usually in the form of a CONTRIBUTING.md file, should include information on how one should submit a pull request or open an issue for your project and what kinds of help you’re looking for (bug fixes, design direction, feature requests, etc.).
You can improve the efficiency and quality of your project by automating maintenance tasks and testing. Automated maintenance and testing can continuously check the accuracy of your code and provide a more formal process for approving contributor submissions. This helps free up time so you can focus on the most important aspects of your project. The best news is that there are plenty of tools that have already been developed and may fulfill the needs of your project.
- Set up automatic testing for incoming contributions by requiring status checks. Make sure to include information about how testing works for your project in a
- Check out the tools that have been developed to automate maintenance tasks. Several possibilities include automating your releases and code review, or closing issues if an author doesn’t respond when information is requested.
Keep in mind that less is more. Be intentional about the processes and tasks you choose to automate in ways that can optimize efficiency, production, and quality for your project, yourself, and contributors.
If you are an active participant in an open source project, this post is for you. It explains how to maintain your software throughout the release cycle and by following a few simple steps: it empowers you to help the project maintain its momentum through regular releases and helps you get more hands on experience.