Best Practices for Maintainers of Open Source Projects

A maintainer can have an easy life from documentation to leveraging the community.

Who is a maintainer?

A maintainer codes and addresses issues in an open source project. When you become a maintainer for a popular open source project, you will notice that your coding decreases and attending to issues increases. Your interaction with users and contributors will increase significantly.

When the project is still young, you are more focused on your ideas and what you want to implement. Most, if not all the time, you make decisions on your own. As the project gains popularity, you find that your time is taken by interactions with users and contributors. Project maintenance is more than code with more unexpected tasks that are equally important. Below are a few ways to ease your maintenance job, from documentation to community leveraging.

Writing down your Processes

Documentation is the most vital task for any maintainer.

When everything is out in the open, people find it easy to contribute. Documentation is not only vital for clarity of your thoughts but explains what you need or what you expect from users before they ask. When everything is well-documented, it becomes easier to turn down ideas outside your scope.

Whatever you do, whether you opt to write full paragraphs or a brief bullet list is better than no writing at all. Always strive to keep your documentation updated and when you cannot do this, indicate outdated files so that contributors can be informed that they are welcome to give updates.

Document your project’s vision

In your README file, outline your project’s goals, or opt for a separate VISION file. Publicize all artifacts that can be useful for your project like the roadmap. A well-outlined vision keeps you focused and avoids scope creep from your contributors.

As a new maintainer, one person narrates how he regrets steering away from his vision in the early stages of his project when he got his first feature request. He appreciates that a clear vision has kept him focused and helped him prioritize important requests.

Document your expectations

When new users come on board, they have no idea about you or your project. Some assume you are an employee, especially if they use your project regularly and depend on it. This perception might have stemmed from the ample time you gave to your project before, but this does not always last when you have other things to attend to. While this is unavoidable, ensure that you let others know you won’t be available as much as you used to be. If you won’t be on the project on weekends, let the community know this.

While rules seem like you are policing others and killing all the fun, they are vital for your project’s success. They can be nerve-cracking, but when enforced fairly, they are empowering to maintainers. These rules will protect you from getting dragged to do things outside your scope.

If you’re a part-time maintainer or a volunteer, make sure, to be honest about it and tell everybody how much time you can dedicate. This is not a reflection of how much time is required for the project. Some of the rules worth documenting are:

The procedure of reviewing and accepting contributions (Indicate if tests are required or if there is an issue template).

Acceptable contributions (Indicate if you want partial help with your code).

Indicate the appropriate time to do a follow-up (You can say something like, ‘Expect a response from a maintainer in 7 days. If you haven’t heard anything by then, feel free to contact us).

Communicate about your availability on the project per week (You could say, ‘we spend 5 hours per week on this project.’

All communication should be made public

Whenever possible, keep everything public. When you have a private maintainers meeting, document the details of the meeting, even if it’s in notes form, and put them out in the public. This makes sure that new members are integrated into the project and become on par with everybody else.

When a user tries to have a private discussion about a feature request, politely direct them to a public channel like an issue tracker or mailing list. Write down all your interactions without fail

Saying no

The maintainer needs to constantly remind people about existing information even when everything is properly documented and in the open. When all rules are written down, you will depersonalize a situation when enforcing those rules

The choice of words when turning down a contribution is key. You can say ‘your contribution doesn’t match the criteria of this project instead of ‘I don’t like your contribution.’ The word no will come up in many situations as a maintainer. Situations like someone derailing a conversation, a contribution that doesn’t match the scope of your project, and doing unnecessary things will require a firm no.

Maintain a welcoming conversation

When a project is public, all manner of contributions will steam in including those outside your scope. The idea can be good with a poor implementation or it’s simply not in line with your vision. A firm no will be inevitable on your pull request queue and issue. Whatever the case, you must be tactful in handling such requests. If you adopt a mechanism of ignoring unfavorable requests or pretending not to see them, you will end up hurting the contributors and demotivating other contributors in your community. When you ignore contribution, you send negativity to the community.

The thought of saying no is terrifying, but it’s inevitable. This, by no means, shouldn’t make you guilty because a yes is forever, but a no is temporary. Never leave an unwanted contribution open to seem nice or to avoid hurting others. This will come back to haunt you when things start to feel intimidating and stressful. Close contributions that you are sure you don’t need, immediately even if you have a backlog. You can adopt a triaging mechanism for your issues.

The first contribution is never easy for new users, and you need tact to handle this. Always thank people for their interest before turning them down. If you need to turn down a contribution:

Appreciate the contribution with a ‘thank you’.
Explain why you have rejected it and offer some relevant suggestions. Keep it firm, but kind.
When issues you don’t want to accept keep repeating, add them to your documentation to avoid repetition.
After responding with 1 or 2 sentences, close the request.

When you reject the idea, this doesn’t mean that you reject the person, and therefore you do not feel to harbor any guilty feelings. You are not obliged to accept a contribution to please people. While maintaining kindness and being responsive, only accept ideas that are aligned to your project. When you practice saying no, it becomes easier with time.

Take a Hands-on approach

In your contributing guide, be precise on the reviewing and acceptance process. This way, you will save yourself from a high volume of unwanted contributions. If the low-quality contributions surpass the high-quality ones, you should put a measure in place for contributors before they get to the submitting stage. Some of the measures you can put in place include:

Request contributors to fill out a PR checklist or template.

Opening an issue before submitting a PR.

Being proactive is the surest way to eliminate unwanted contributions. You’ll also be saving contributors from investing their time in something that will ultimately get rejected. Ultimately, your workload reduces and becomes manageable.

At first, you might get criticized as people get upset for rejecting their ideas. If any person ignores the rules, close the issue immediately and direct them to your documentation. It might seem unkind, but it is the surest way to keep things focused. If the hostility escalates despite efforts to calm things, you should remove them from your community.

Promote mentorship

When a willing contributor always submits substandard contributions, it can get frustrating for them. If you encounter someone enthusiastic about the project but are constantly getting rejected, exercise patience. Keep explaining clearly why you have rejected each contribution and try to point them in the direction of easier tasks like something marked as a ‘good first issue’, and they can grow from there. You can mentor them from that point if you have some time to spare or find someone who can mentor them.

Engage your community

Your community can come in handy to offer you a helping hand. That’s why it’s there in the first place, so you don’t need to overburden yourself. If your community is not active and has many users, put the users to the task.

Delegate the workload

You might want a temporary break or to leave the project permanently, and you can ask someone to take over. You can identify enthusiastic people and give them commit access or simply hand it over to someone else completely.

Ask for help if you want people to pitch in. The best way to get help is to label simple tasks for beginners to tackle. GitHub works by distributing these issues all over the platform to increase their visibility. When you notice an enthusiastic and positive contributor, reward them by assigning more tasks and documenting how others can take up leadership roles in the project. Encourage the community to share ownership of the project to ease your workload.

If someone is maintaining your project elsewhere, you can link the fork to your original project. It is a plus for people to want to keep your project alive.

A maintainer found that documenting his project’s vision helped his goals thrive long after he stepped away from the project.

Encourage forking among the community

When you let community members fork, they can exercise their creativity on their projects without interfering with your vision. As a project grows, it becomes inevitable for maintainers to take a conservative approach in their introduction of new codes. As much as you keep saying no, there are people with legitimate needs, and that is when you end up turning your project into a platform.

You might encounter a contributor whose opinion differs from your project. You should gently steer them towards starting their fork. Duplicating a project is never a bad thing in open source projects.

When a user requires a solution you do not have the bandwidth to build, you can offer APIs and customization hooks to meet their needs. According to one maintainer, encouraging plugins for Cocoapods created some interesting ideas.

Bring in the bots

As a maintainer, you must have sort help from fellow humans. Similarly, you can seek help from robots to accomplish some tasks.

Introduce tests and other checks to level up your code quality

Make a requirement that contributors should pass the test before making any submissions. That way, you will reduce low-quality submissions by a country mile.

When a contributor is subjected to a test, they gain confidence as they go, especially when they pass. This is the simplest way to automate your project without having to manually reject contributions. When you increase your responsiveness, you increase your community’s engagement. The surest way is to run automated tests on all incoming contributions, but ensure that they can easily be run locally.

When using GitHub, you should put a status check requirement to ensure that no change merges happen without passing the tests. Ensure that you add how these tests work on your CONTRIBUTING file.

Utilize available tools to automate simple maintenance tasks

There are available tools for maintenance and automation. Working on a popular project is easy as other maintainers have walked the path before, experienced similar problems, and made solutions. GitHub offers templates and pulls requests for contributions like bug reports which can be used to streamline received communication.

Taking a break is okay

Burnout is unavoidable in open source work, especially for maintainers. You might find that the joy you once felt while working on your project has been drained. You could be feeling overwhelmed and stressed out by the mere thought of your project as issues keep piling up. The success of your project is proportional to your happiness, and therefore should be non-negotiable.

When this happens, it’s time for a break. Do not wait until you can barely function to take a vacation. Taking regular breaks is vital for your health and refreshment, and you will find that you enjoy your work more. One Python core developer by the name of Brett Cannon took a month off after 14 years of volunteer work. Sometimes, you might feel obliged to stay and keep working when you think that everybody depends on you. Don’t do this. All you need to do is inform people when you aren’t available to avoid confusion from your sudden unresponsiveness. Breaks do not have to be about vacations. You can take weekends or working hours off from the open source, but communicate first to prevent people from bothering you.

You come first

As a maintainer, you will incorporate both personal and leadership skills at a level many will never experience. While it is not always comfortable, definite boundaries and only taking up what you can handle is the surest way to a happy, reproductive, and refreshed life.

When a project grows from its initial stage and becomes popular, the maintenance skills increase as well. This is not a bad thing as it is super rewarding, but you need to take care of your well-being before anything else.

Press ESC to close