A Vegan walks into a smokehouse,
walks up to the counter,
asks to see the manager,
demands that the restaurant offer vegan-friendly options,
hands the manager a cookbook full of vegan-friendly recipes,
gets rejected,
walks out of the restaurant,
and leaves a 1-star review.
To the average human being, appeasing the specific demands of an individual who has no regard for your time, work, or budget sounds ridiculous. On the other hand, the average human being does not take into consideration someone else's time, work, or budget.
As an open source maintainer myself, I have come to appreciate the strenuous work of the giants whose shoulders I stand on. I want to surface how much these people are doing, and I want to help you appreciate and contribute in as frictionless a way as possible.
Who is this article for?
Whether you are getting started in Open Source, a vibe coder, or an opencl*w instance, hopefully this article will do you some good.
This article assumes you have a basic understanding of a version control system like git, and that you have some familiarity with a git hosting provider like Github or Gitlab.
How to be a headache for Maintainers
Let's talk about some ways you can be an absolute pain to open source maintainers.
Side effects may include getting bad publicity on social media, getting banned from the project, or just getting butthurt after your issue or pull request was rejected.
How to get your Issue rejected
Submit an extremely vague bug report
Request a port to a different language/framework/operating system
Pitch a large-scope feature request
Open a vague PR for the sole purpose of trolling
How to get your Pull Request rejected
Vibe code a massive feature implementation
Open a Pull Request that adds your name to README.md
Being a Civilized Contributor
Now that you have a general idea of what not to do, let's go over some ways that will help you work more seamlessly with open source maintainers and contributors.
General Etiquette
Applies to both issues and pull requests.
Express your Gratitude - Open Source Software may be free to use, but time isn't. If a project is important to you or has helped you, express your gratitude to the maintainers, because that's what keeps them going. If you can spare a few dollars, consider sponsoring the project.
Search and Read - Are there any duplicate issues similar to yours? Are there any workarounds? Has someone written a blog post to fix the exact issue you're dealing with? Finding an existing solution or a workaround is more valuable than getting a delayed response.
Be Verbose - Provide as much information as possible. Cross-reference relevant issues and Pull Requests. Make it easier for the maintainer(s) to help you.
Issues
Issues count as contributions on your github graph for a reason. Stop thinking of issues as customer support. Start thinking of issues as a way to positively contribute to the project.
Before you open an issue, take into consideration how much engineering effort is available. How many active maintainers are there? When was the project owner last active? How many open issues are there?
Avoid introducing unnecessary overhead - Will your issue provide a solution if completed, or just introduce more problems and overhead? For example, requesting Windows support for a Mac and Linux-only application will come with its own set of problems.
Estimate the impact - Does your issue describe something with a large impact that affects the majority of the consumer base, or is it very specific to you? Maybe a workaround, forking the repository, or a dependency patch will work better than waiting a few months for the next version to be released.
Pull Requests
When opening a pull request, it is important that you adhere to the style guides and conventions specified in the project as much as possible.
Throwing code at a repository and hoping it gets accepted usually doesn't work. Taking the time to make a clean and beautiful Pull Request shows the maintainers that you really want it.
Retain clean commit history - Take 30 minutes to learn how to squash, describe, reorder, and rebase commits. Split your changes into small, very verbose commits that cross-reference other related issues and pull requests. Explain why changes are being made, not just what they do.
Automated Testing - If there is a testing environment in the project you're contributing to, it doesn't hurt to write a unit/integration test to ensure correct behavior.
You as a Maintainer
Being a maintainer or project owner comes with a set of responsibilities. If you want to build a reliable piece of software for people to use, you should dedicate the time and effort to keeping it that way.
Accepting Contributions - You as a maintainer should not blindly accept contributions from external contributors without testing and thorough review.
Be Transparent - When accepting, rejecting, or commenting on contributions, let the contributor know why you came to your decision.
Be Organized - It is extremely important that you as a maintainer are organized in how you manage issues, pull requests, and write commits. Break changes into PRs and commits and describe them in detail. Cross-reference issues and pull requests. Don't close an issue as "completed" if it isn't completed.
Being "nice" is not your focus - It's okay to be blunt as long as you are verbose. Don't give external contributors the impression that you're going to accept their every contribution. Rejecting a contribution might hurt someone's feelings but won't hurt your project. It's okay to say "no".
Delegate work when necessary - It is unlikely that you can work on your project full-time, because OSS usually doesn't pay the bills. If a past contributor or someone who opened an issue expresses interest in your project, ask them to make a PR which you can later review.
Archiving - if you can no longer work on an open source project of yours due to personal reasons, archive it to let people know that development has ceased.
Conclusion
This article just scratches the surface of what all is in being an open source contributor and maintainer.
If you got something out of the article, I hope you take the time to apply it and make the lives of open source contributors and maintainers easier.
We're all in this together. Let's share the load.
Top comments (0)