A recent episode of #devDiscuss on Twitter about open source caught my attention in a tick!
The question about what you should know about being a good citizen of open source sparked a great discussion on the general etiquette in open source communities: What makes newbies trip up? What do experienced OSS contributors often mess up on in terms of etiquette?
Since open source is an issue I feel very strongly about, I absolutely wanted to wrap up all the superb twitter comments into on article. 💛 😊
Plus, I do think it is important to talk about (etiquette in) open source. After all, open source software already plays a big role in today's digital world. So understanding the people behind these projects is not only important to anyone concerned about the sustainability of open source, but also to the services and technologies that depend on it.
About the General Etiquette in Open Source Communities
While there is no general rule for etiquette, there is a common sense on how we should behave and should not behave when interacting with other humans — well, at least I assume that all of us do apply these common sense practices. Also, most projects do have some kind of code of conduct, many even explicitly did write it down.
Common points often are
- don’t hate
- don’t insult
- don’t threaten
- don’t troll
- be nice and respectful to others
Self-evident, right?! Not quite. Unfriendly and disrespectful behavior are a lot more frequent than you might think - particularly within the open source communities.
Another day doing open source.. I think we've reached a new low here, but it's all about how you decide to take it. I rather laugh. #nsfw pic.twitter.com/1nZ9MzQVRs
— Jordi Boggiano (@seldaek) 7. September 2017
By all means, I'm aware, that open source brings together a lot of diverse people from all over the world, and that this can indeed lead to conflicts, but that should not prevent us from behaving with respect.
About Common Conflicts and Problems encountered in Open Source
According to the 2017 Open Source Survey (hosted on GitHub) dismissive responses, conflicts, and unwelcoming language or content are among the top problems that are encountered in open source. Incomplete or outdated documentation is 'a pervasive problem, observed by 93% of respondents, yet 60% of contributors say they rarely or never contribute to documentation'.
Also, the survey reportedly reveals that negative behavior (rudeness, name calling, and stereotyping) are yet infrequent, but still up to 18% of open source contributors have 'personally experienced a negative interaction with another user in open source', and '50% have witnessed one between other people'.
The complete open source survey can be found here.
Please Note: The survey collected 5,500 randomly sampled respondents sourced from over 3,800 open source repositories on GitHub.com, and over 500 responses from a non-random sample of communities that work on other platforms. The data and questionnaire are released under CC0-1.0.
One might think these findings are not that meaningful. Others might suggest the survey is not a representative cross section.
But either way, we should be aware that negative interactions impact many more than the immediate participants. Due to the public nature of open source, 'negative interactions are highly visible', and as a result, 'discouraging effects can extend far beyond the individuals that are directly involved'. So it's quite likely that negative long-term consequences for a project's activity would follow from any negative interaction.
But now, how are we — as contributors, maintainers, issue reporters, and others — a good citizen of open source?
About being a good citizen in Open Source
First and above all, regardless of being a contributor or maintainer:
Keep it classy!
Open source is often made up of enthusiastic Individuals from all over the world. While most conversations are hold in English, be aware that English is not the first language for everyone. Context can get lost across languages, cultures, geographies, and time zones. Also, written communication makes it harder to convey a tone or mood. Just assume good intentions in these conversations.
Checklist for Contributors *
As a contributor remember to
- read the docs, the README, issues, or mailing lists
- It's totally OK to ask questions or for help, but do your homework beforehand.
- read the project's contributing guideline
- follow the project's contributing guidelines
- look at existing issues before opening a new one
- give context and provide as much info as possible when reporting a bug
- keep communication public wherever possible
- keep requests short and direct
- be patient
- respect the community's / maintainer's decision - even if it doesn't fit in your plans
- stick to existing coding style, and patterns
If you are looking for a place to start contributing, a not-so-obvious place to start is the documentation, especially if you're a beginner! It's hard for core teams or normal contributors to figure our what's currently missing for beginner. #DevDiscuss https://t.co/4dkLClGTve
— Prem Sichanugrist (@sikachu) 20. Dezember 2017
(I know I'm repeating myself but) Documentations are crucial. So when you run into documentation issues, help a maintainer out and open a pull request that improves them (documentation too can be a good place to make your first contribution).
New to contributing to open source projects? Your first step is reading the contributor guidelines and code documentation. Everyone wins when guidelines are followed. #devdiscuss
— Kelly Vaughn 🎄 (@mrskellyvaughn) 20. Dezember 2017
When making a contribution or submitting a pull request, stick by the maintainer's choice for his code organization. In most cases, he or she will still be there maintaining the code when you've already gone on to new open source adventures.
If you're feeling an overwhelming urge to refactor the code, get in touch with the maintainer before doing anything!
As a contributor, be flexible and open to making changes to your submission. Odds are, you won't be maintaining the code you just wrote, and a good maintainer will guide you to producing better code. #DevDiscuss https://t.co/vxY1zC9Jf7
— Joseph Moore (@thatjoemoore ) 20. Dezember 2017
Oh and *most* people forget this sooner or later: maintainers are usually giving their time for free. Be considerate. #DevDiscuss https://t.co/iQhLxth90f
— Nick Craver (@Nick_Craver) 20. Dezember 2017
Checklist for Maintainers
Most of the discussion has been about what contributors shall do - or shall not do. But let's not forget, that both parties are in demand.
In General, writing things down is one of the most important things you can do as a maintainer, because documentation helps orient newcomers a lot: how a project can be used, what the contribution process is like, the terms of use and contribution, plus the standards of conduct in a project's community.
Also, as a maintainer remember to
- set-up Code / Test Coverage and continuous integration (it'll make your life a lot easier)
- There are a lot of options, many use TravisCI as it is an easy to integrate with GitHub and other repository services.
- add a license
- Licenses are by far the most important type of documentation to both users and contributors in deciding whether to use / contribute to a project
- Plus, this is especially interesting for companies who count on open source projects, they'd tend to not use (your) open source projects when there's no a license added.
- provide a project documentation
- provide contributing guidelines
- provide Demo when possible and useful
- provide issue templates
- thank people
- be nice and welcoming
- keep communication public wherever possible
- communicate even if you're not accepting a pull request - but be considerate
- be decisive and learn to say no
Further advices have been:
address problematic behavior swiftly, politely, and publicly, to send a signal to potential contributors that such behavior isn’t typical or tolerated.
use clear and accessible language for people who didn’t grow up speaking English, or read less-than-fluently.
*Please keep in mind, these checklists are a miscellany of tweets and personal suggestions. Nothing's set to be stone!
Just try to leave the Internet a better place than when you found it!
Happy contributing! 💛 😊
When the maintainer says in an issue "I wish I knew how to do that..." and you're all like... #DevDiscuss pic.twitter.com/hVbRiANlDm
— David Muckle (@dvdmuckle ) 20. Dezember 2017
Resource
- https://github.com/blog/1184-contributing-guidelines
- https://opensource.guide/
- http://opensourcesurvey.org/2017/
- #devDiscuss on Twitter
Top comments (4)
Nice article, great advice.
Recently I came across an issue on Github which shocked (and slightly humoured) me github.com/kenwheeler/slick/issues... (warning contains some swearing) - wow, perfect example of how not to go about this.
The interesting thing is the solution to the css issue does fix the problem. If only the person raising the issue had contributed in a friendly manner.
Yep yep, thanks for this. I didn't read on through the whole project, but the revealed behavior within this issue is a good example for ... well, how you should not behave.
Being a 'twerp' (ehm, may I say that?! 😄 ) won't help any project, issue, bug (...).
... and writing this article already paid off. 🙂 😄
Some comments may only be visible to logged-in visitors. Sign in to view all comments.