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.
Hong Kil-dong (1986) by Kil-in Kim 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
