Here 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.
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.
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.
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 StackOverflow: 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?
Published on Java Code Geeks with permission by Yegor Bugayenko, partner at our JCG program. See the original article here: Open Source Etiquette Opinions expressed by Java Code Geeks contributors are their own. |
