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.
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.
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.
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'.
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?
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.
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
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.
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! 💛 😊
- #devDiscuss on Twitter