ossHere is a short list of common courtesy rules for open source software development. Actually, they apply elsewhere also, but they are most visible when you do GitHub-based coding. I strongly believe that sooner or later all programming will be open source and these rules will apply to everybody. Consequently, it makes sense to start following them now, whether you are an active Apache contributor or a happy owner of the “Java for Dummies” book.
In no particular order:
Make Small Pull Requests. Some recent research done by Caitlin Sadowski et al. from Google and the University of Zurich demonstrated that there is a strong correlation between change size and review quality: larger changes (pull requests) negatively affect quality. According to this article, Google developers are strongly encouraged to make small, incremental changes. Aside from Google, many others explicitly say the same: Microsoft, Zalando, Atlassian, and OpenSource.com.
Don’t Unite Changes. It may be tempting to put all changes you want to make into a single pull request, to merge them faster, having only a single review. Don’t do this. This will only make the process more complicated and you will annoy your reviewers. The rule is simple: one change = one pull request.
Use Nice Markdown in Your Docs. I didn’t manage to find any scientific research on this, maybe because it’s obvious: the text “why is f nil?” is much easier to read than “why is f nil?” Rich text formatting not only makes the text look nicer, but also helps readers digest the content faster and with more pleasure. After you learn Markdown, I’d suggest reading this blog post by Aaron Stannard from PetaBridge: How to Use Github Professionally.
Address Your Comments. Always, without any exceptions, start your comments (either in a pull request or in an issue) with GitHub nickname of the person you talk to. If you don’t do this, the message will not reach the person’s inbox and most likely will be lost. People who are active in GitHub receive hundreds of emails every day from from GitHub: they don’t read them. They only read what lands into their “Notifications.”
Say Please, Thanks, and Sorry. According to Pope Francis, the recipe for success lies in saying three simple words. He didn’t mean open source developers, but the advice perfectly applies to us programmers. There are tons of articles written about online etiquette, all of them are basically the same: ask nicely, be grateful, and be ready to admit a mistake. I would recommend 15 rules for communicating at GitHub by Ben Balter, a Senior Product Manager at GitHub.
Ping Them. When you make some changes to the branch and want your pull request to be reviewed again: post a message explicitly asking your reviewer to take another look. When you submit a pull request, post a message into it addressing it to the architect of the project: ask them to review the PR. And so on. Don’t expect them to watch your activity. They have other things to do. It’s your responsibility to ping them.
Make Descriptive Commits. The style of formatting Git commit messages (I’m sure you are using Git) is usually very specific in each project. However, there are some similarities and common rules. I would recommend these blog posts: How to Write a Git Commit Message by Chris Beams, Some tips on commit etiquette by Jeremy Gunter, and A Note About Git Commit Messages by Tim Pope. Also, check these out: conventionalcommits.org and 50/72 Formatting.
Have an Avatar. A study by Kristine L. Nowak et al. from the University of Connecticut, demonstrates that users with avatars, especially feminine and anthropomorphic ones, are more likely to catch attention than those who have no profile pictures (or have default ones provided by GitHub). Of course, it’s not only the avatar that matters; your GitHub profile must also have many other things: description, email, pinned repositories, etc. Use this profile as an example: @m0nica.
Stay Online. Offline communication is much cheaper than online tickets: just shout out a question in the office and you get an answer immediately. No need to write those long tickets, formulating questions in English, waiting for the assignee to post an answer, and so on. However, offline talk hurts the project, for so many reasons. Every time you move from a GitHub issue to a Slack chat to discuss the problem, you are doing a disservice to the project and all its participants. Remember that.
Report Nicely. Just like with Git commits, bug reporting rules differ from project to project, but the basic principles remain the same. Just google “how to write a bug report” and listen to what those bloggers say. Your bug reports demonstrate who you are even better than your code. You may practice by submitting questions to Stack Overflow: the community there will punish you for all your mistakes, quickly training your reporting skills.
Make Elegant READMEs. I wrote about this before: the importance of a perfectly written and formatted README file in an open source project is difficult to overemphasize. Writing good code is important, but presenting it is part of online etiquette: high-quality documentation means respect to the users of your products.
This seems to be it. If you do all of these, you will demonstrate respect to other developers and they will respect you in return. Did I forget anything important?
What does it take to be an active and successful #opensource contributor?
— Yegor Bugayenko (@yegor256) March 21, 2021
