Dos and don'ts in open source
I remember how careful I was the first time I opened a GitHub pull request. I read, re-read and triple-checked every one my comments before posting. It felt scary publishing my thoughts online because I was afraid people would judge me or misinterpret me.
Today, I comment with more efficiency and confidence. According to GitHub, I made 19 thousand "contributions" during the period 2016-2019.
I quote "contributions" because it's not a good metric to measure the actual value of anyone's GitHub activity. I use the metric only to emphasize the volume of comments that I have posted while staying motivated to continue working on open source.
I enjoy working on open source just as much today as when I started. In this post I want to share some principles I try to follow to avoid unproductive discussions and invest my focus on what matters the most. Some of these dos and don'ts might be useful for maintainers, some for contributors. Whatever your role in open source, I hope you find some useful tips.
Do: keep emotions out
It's normal that software doesn't work as expected. It's also normal to feel frustrated when software doesn't work as expected. However, it's not OK to let that frustration leak when you comment online.
When you're feeling frustrated, look towards friends and colleagues for help instead of GitHub. If you don't have somebody to reach out to, consider closing your computer and taking a break instead of publishing your thoughts online.
This applies to both users and maintainers. As a maintainer, I have often felt uncomfortable reading a passive-agressive issue pointing out an embarrasing bug. I can't count the times I've spent 10 minutes drafting a response in distress only to delete the draft, do something else instead and return to the issue a few days later. I have never regretted doing this.
Do: call out bad actors
Sometimes discussions go in the wrong direction. Consider calling out bad behavior when you feel a person is actively harming the discussion.
When calling out misbehavior, focus your attention on how to provide constructive feedback. Don't shame the person. Assume that most people are commenting in good faith.
Beware that calling out misbehavior of people online requires a lot of energy. When you do this, make sure you're not hungry, you've slept OK and are in general feeling well. Ask a collaborator to help if you don't have the energy.
To give a concrete example, here is an issue that was once reported to one my projects:
Title: scala 2.13 support. Description: Hi, Yup, I've seen that it's hard and so on. Though 2.13 is our inevitable future. So, scalameta has to support it or cease it's existence.
I responded to this ticket by closing the issue, opening a new "Cross-build for 2.13" ticket and commented
Superseded by NEW_TICKET. Threats like this is not a nice way to start a discussion, I ask you to be more respectful in future communications. Here is a template you can use for reference
Hi, I am using Scalameta in my project and I would love to upgrade to 2.13. I saw the plans to support 2.13-M2 in #1023 had been dropped, would it be possible to revisit that decision?
If you can't come up with constructive feedback you may want to mute or unsubscribe instead. Most importantly, do not continue the discussion like normal because it sends the message to other people that the misbehavior is acceptable.
Do: stick to the template
A lot of issue trackers have a bug report template with the items:
- Steps to reproduce
- Expected behaviour
- Obtained behaviour
It's sometimes hard to fill these out because it takes time to come up with a reliable reproduction. As a reporter, please take the time and try to stick to this template because it makes the conversation much more productive. Even if the project is not using an issue template, I still encourage you to formulate bug reports in the "steps to reproduce, I expected, I obtained" format.
Do: invest in collaborators
As a maintainer, I wouldn't still be doing open source today if I only worked alone. Don't get me wrong, I have worked alone on certain projects for long periods of time and these have been some of my favorite times working on open source. However, the projects I'm most proud of today and the projects that motivate me to continue working on open source have multiple collaborators.
Here are some ideas:
- Automate releases so that the project can be released on a tag push. Avoid the situation where a release is blocked by one person having to do manual steps on their computer. Automatic releases are empowering for collaborators and helpful in situations like when you are away on vacation.
- Start responses to issues and pull requests with phrases like "Thank you for reporting!", "Thank you for this contribution!". Don't use a template to auto-fill this sentence. Write it out word by word to test whether you genuinely mean it, if you don't mean it at the moment then it's OK to wait with responding.
- Chat privately with active collaborators. Some topics are easier to discuss informally via DM instead of in a public forum.
Do: mute and unsubscribe at will
Some discussions are less important than other discussions. Not every discussion requires your input.
Don't be afraid to use the unsubscribe button in these cases. If the discussion is important enough and your input is truly needed, somebody will eventually to reach out through another channel.
Don't: use "good first contribution" labels
This may be controversial, I'm open to be convinced otherwise.
I'm on the fence about the value of "Good first contribution" labels. My experience is that these labels often attract the wrong kind of contributions. It's best when the contributor has an itch to scratch and is personally excited to enjoy the fruit of the contribution.
I suspect the "good first contribution" may also be distracting for well-intentioned contributors. Don't let the lack of the label discourage you from working on a ticket.
In the absensce of the label, my advice to aspiring contributors would be to find a project you personally use and identify a feature you're excited about using or a bug you'd like to see fixed. If you don't think you'll use the change after its merged, try to find something else to work on. It doesn't have to be an existing issue, it's OK to create a new ticket. Make sure to consult with the maintainers to get a green light on the change and get an estimate for hard it would be to implement. Avoid working on a very ambitious change as your first contribution.
Don't: make promises
It's tempting to respond to a welcome contribution with a quick "This looks amazing, I will review tomorrow!". Considering giving a thumbs up reaction instead and wait with commenting until you complete the review.
Promises are estimates and estimates are hard. Unless I'm bound by a paid contract, I try to avoid promising my future time no matter how confident I am about delivering on the promise.
Don't: talk negatively about other projects
Most projects are created as some alternative to another project. Avoid dragging down competing projects when evangelizing to people why they should use your project.
Most open source software is created by some person who was trying to solve a problem that was relevant for them at a given point in time. Your situation is bound to be different on some level. It's fine to compare projects, but do it in a way that's respectful of other people's contributions.
What are your dos and don'ts?
Having healthy online conversations is essential for any open source community and this post only touches the surface of this topic. I'm curious to know what other people think.
What are your dos and don't in open source?
Thank you Borja for reading over this post and providing valuable feedback.