Open source software is thriving. Large corporations are building on software that rests on open collaboration, enjoying the many benefits of significant community adoption. Free and open source software is amazing for its ability to bring together many people from all over the world, and join their efforts and skills by their interests.
That said, and because we come from so many different backgrounds, it’s worth taking a moment to reflect on how we work together. The manner in which you conduct yourself while working with others can sometimes impact whether your work is merged, whether someone works on your issue, or in some cases, why you might be blocked from participating in the repository in the future. This post was written to guide people as best as possible on how to keep these communications running smoothly. Here’s a bullet point list of etiquette in open source to help you have a more enjoyable time in the community and contribute to making it a better place.
For the Maintainer
- Use labels like “help wanted” or “beginner friendly” to guide people to issues they can work on if they are new to the project.
- When running benchmarks, show the authors of the framework/library/etc the code you’re going to run to benchmark on before running it. Allow them to PR (it’s ok to give a deadline). That way when your benchmark is run you know they have your approval and it’s as fair as possible. This also fixes issues like benchmarking dev instead of prod or some user errors.
- When you ask someone for help or label an issue help wanted and someone PRs, please write a comment explaining why you are closing it if you decide not to merge. It’s disrespectful of their time otherwise, as they were following your call to action. I would even go so far as to say it would be nice to comment on any PR that you close OR merge, to explain why or say thank you, respectively.
- Don’t close a PR from an active contributor and reimplement the same thing yourself. Just… don’t do this.
- If a fight breaks out on an issue that gets personal, shut it down to core maintainers as soon as possible. Lock the issue and ensure to enforce the code of conduct if necessary.
- Have a code of conduct and make its presence clear. You might consider the contributor covenant code of conduct. GitHub also now offers easy code of conduct integration with some base templates.
For the User
- Saying thank you for the project before making an inquiry about a new feature or filing a bug is usually appreciated.
- When opening an issue, create a small, isolated, simple, reproduction of the issue using an online code editor (like codepen or codesandbox) if possible and a GitHub repository if not. The process may help you discover the underlying issue (or realize that it’s not an issue with the project). It will also make it easier for maintainers to help you resolve the problem.
- When opening an issue, please suggest a solution to the problem. Take a few minutes to do a little digging. This blog post has a few suggestions for how to dive into the source code a little. If you’re not sure, explain you’re unsure what to do.
- When opening an issue, if you’re unable to resolve it yourself, please explain that. The expectation is that you resolve the issues you bring up. If someone else does it, that’s a gift they’re giving to you (so you should express the appropriate gratitude in that case).
- Don’t file issues that say things like “is this even maintained anymore?” A comment like this is insulting to the time they have put in, it reads as though the project is not valid anymore just because they needed a break, or were working on something else, or their dad died or they had a kid or any other myriad human reasons for not being at the beck and call of code. It’s totally ok to ask if there’s a roadmap for the future, or to decide based on past commits that it’s not maintained enough for your liking. It’s not ok to be passive aggressive to someone who created something for you for free.
- If someone respectfully declines a PR because, though valid code, it’s not the direction they’d like to take the project, don’t keep commenting on the pull request. At that point, it might be a better idea to fork the project if you feel strongly the need for a feature.
- When you want to submit a really large pull request to a project you’re not a core contributor on, it’s a good idea to ask via an issue if the direction you’d like to go makes sense. This also means you’re more likely to get the pull request merged because you have given them a heads up and communicated the plan. Better yet, break it into smaller pull requests so that it’s not too much to grok at one time.
- Avoid entitlement. The maintainers of the project don’t owe you anything. When you start using the project, it becomes your responsibility to help maintain it. If you don’t like the way the project is being maintained, be respectful when you provide suggestions and offer help to improve the situation. You can always fork the project to work on on your own if you feel very strongly it’s not the direction you would personally take it.
- Before doing anything on a project, familiarize yourself with the contributor guidelines often found in a CONTRIBUTING.md file at the root of the repository. If one does not exist, file an issue to ask if you could help create one.
Final Thoughts
The overriding theme of these tips is to be polite, respectful, and kind. The value of open source to our industry is immeasurable. We can make it a better place for everyone by following some simple rules of etiquette. Remember that often maintainers of projects are working on it in their spare time. Also don’t forget that users of projects are sometimes new to the ever-growing software world. We should keep this in mind when communicating and working together. By so doing, we can make the open source community a better place.
It is so cool to read this post from two of my idols. How I and other humans communicate about code is something I think about quite a bit.
This post opened my mind to new ways of considering communication on open source projects.
As a maintainer, I’ve done things listed above incorrectly—which is/was not intended and reading this post helped me to reflect on my errors. I immediately want to know what I should have done to make the experience for all better.
Could either of you (or someone) follow up with suggestions on what to do when communicating on open source projects?—Maybe even write what to do right under what not to do as child list items?
Thanks again! I am definitely going to keep this post in my mind.
Hi Jeff!
Thanks for stopping by. There’s only one bullet point in the maintainer’s section for what not to do, and it’s about not closing a PR from an active maintainer and reimplementing it yourself. Is that the one that you’re referring to needing clarity on?
What does “PR” mean?
“Allow them to PR (it’s ok to give a deadline)” …
“When you ask someone for help or label an issue help wanted and someone PRs,” …
“it would be nice to comment on any PR that you close”…
Hi Roger!
Sorry about that, PR stands for “pull request”. Here’s a post from github that explains what pull requests are in detail: https://help.github.com/articles/about-pull-requests/, hope that’s helpful.
Best wishes!
Hey Sarah,
Thanks for your response and thanks for clarifying, “only one bullet point”! That is the bullet where I need clarification.
I missed a key word in that statement, active. I have, with a first-time contributor’s knowledge, committed something similar to their work in a separate PR. There was a mixture of reasons for doing this, none of which was to be rude.
What are some ways to assist first-time contributors to a project to ensure their PR is ready?
I am thinking of a few ways as I ask that question and I would love your thoughts too.
Thanks, again!
Great question! You are absolutely correct that a very important word in this sentence is active, Kent and I actually went back and forth a bit on how to word that properly, because it’s an important piece. As you guessed, that wording is mostly important because if someone doesn’t respond for a while and you’re waiting on them, they’re no longer active, and this bullet probably no longer applies.
It is important to try to commit their work if they are active because it gives them credit for their work. Reimplementing something they’ve done can feel like a lack of acknowledgement, which is pretty important when someone is just starting out.
If their pull request is almost something you want but not quite, this is where it gets tricky and I think is probably the crux of your question. You have a few options:
1. You can do several reviews of the PR and help them update and edit it and get it into the right shape. This takes a bit more time and care. You could probably move faster on your own but think about how this scales- if you teach this person how to work through the problem, you might find that they are able to help maintain more and more. We were all learning at one time, this gives back in a way that might be potentially rewarding for you in the future.
2. If you don’t have the time to walk through things with them, you can merge the PR and then work on top of it to make the changes you feel necessary to get it into shape. You can even commit with them, which is helpful because you can get everything in at once.
Other people have ideas about this for sure, and if this advice doesn’t fit your needs, that’s absolutely ok! I think the main thing is if you close out their PR and they are still actively involved, it’s great to give them a why, so that they aren’t left wondering why you reimplemented it without giving them credit. This can avoid a “sour grapes” feeling and encourage them to keep contributing in the future.
As I told in my forward interview more once I thank you for everything you to do for my company.
“Don’t close a PR from an active contributor and reimplement the same thing yourself. Just… don’t do this.”
See this all the time and it really annoys me because they did the work and as such should receive credit for it.