One of the questions we are often asked is "how do I create a community?" But even deeper that: "how do I create a sustainable, healthy, and welcoming open source community?"
Each year, we release the State of a Octoverse; a round up of the top open source projects, languages, stats, and more.
What makes a sustainable open source community?
From our research in 2021, we discovered six key themes that were characteristic of top, successful, and sustainable open source projects. Here's a brief overview of each theme.
Have a README
A README is so important for telling potential contributors what your project is about. READMEs also share information such as an overview of the community, links to other documentation, and how to get involved in the community.
According to our 2021 findings, 14.1% of open source projects still do not have a README file. Those repos with READMEs are 55% more productive than those without. This is because they provide all the necessary information at developers' fingertips.
In 2021, we released Organisational Profile READMEs. This meant open source projects can now highlight who they are as a community. Having an Organisation Profile README can give your community an overview of the types of projects your organisation works on, and the type of community you are building.
If you haven't built your Org Profile README, check out our tutorial:
Your README shouldn't replace the need to have a website. You should have a website explaining the project. This is helpful to both developers and non-developers and helps make your project discoverable across the web. A website is also super helpful for housing your documentation, videos, links to socials, and in particular, demos of your product.
Have good-first-issues
As a new developer coming to a project, it's often hard to figure out what to work on and where to provide value. This is where good-first-issues comes in handy. Good-first-issues are issues tagged by maintainers as being good issues to work on as a new contributor.
According to Nick Young, the maintainer of Project Contour, good-first-issues are issues that any one of the maintainers could easily complete. During our interview with Young, he says the reason for this is ensuring maintainers can actually help the people who come to the project, and provide something to dip their toes into the water.
As a maintainer, you should make an effort to tag relevant issues with the good-first-issue label. It's a default label in all repos, and will encourage contributions.
Have good Contribution Guidelines
Speaking of encouraging contributions, you should ensure you have good contribution guidelines for your project. Contribution guidelines help "elevate the quality" of your project and "share information that makes them more attractive to new contributors".
According to our State of the Octoverse, contribution guidelines help with ambiguity and friction when working with open source projects.
The guidelines act as a "rules of engagement" when developers are coming to contributing to the project. According to the report, there are still over 65,000 open source repositories without any contribution guidelines. Those with contribution guidelines are also 17% more productive than those without.
Contribution guidelines outline various rules of engagement with the project, such as how to get started, when to submit an issue, how to submit a pull request, and more.
Have a Code of Conduct
Contribution Guidelines help to define how to contribute code to the project. A Code of Conduct helps define how people should act and engage with other people on the project. They are really important for ensuring your community behaves in a respectful, meaningful, and impactful manner.
According to our report, the majority of open source repositories still do not have a Code of Conduct.
There are lots of different Code of Conducts you can use as a guide to help you build the one that's right for your community. Some of the information contained in the GitHub Event Code of Conduct can be applicable to your open source community. Microsoft has a really good Code of Conduct pertaining to their open source communities.
There's also the Code of Conduct released on the opensource.guide website, which contains other useful information. Finally, there's the Contributor Code of Conduct that you can use for your open source project.
Ensuring you have a Code of Conduct will encourage welcoming and courteous engagement with your open source project.
Commit to mentorship
One of the best things about open source, is the networking and experience you create by being part of the community. As a maintainer, you need to understand not all developers are as well versed as you.
By maintaining an open source project, you should agree to help mentor and guide contributors. Not only will this make better developers and therefore lead to higher quality code on your project, it will also encourage up and coming developers to take on core contributor and maintainer roles. All this contributes to the overall sustainability of your project.
Projects that foster mentorship have long-lasting benefits for productivity, satisfaction, and retention. Communities with a mentorship mentality also lead to better collaboration.
According to Paul Copplestone from Supabase, mentors should be able to teach you not just about the project, but about the coding language. He says anyone who wants to learn Postgres for example, should contribute to Supabase as he and the other maintainers are committed to teaching developers.
00:30
Get involved in Open Source because the Maintainers will help you
Michelle Duke for GitHub ・ Sep 25 '20
Encourage respectful language in GitHub Discussions
Finally, whilst you might have a good Code of Conduct, contribution guidelines, and an epic README, none of that is worth anything if your conversations have dissolved into conflict.
"Respectful language in GitHub Discussions signal a community is safe, welcoming, and trusted." Communities that have good conversations in GitHub Discussions are more likely to be productive and attract good contributors.
As a maintainer, it's not just up to you to maintain the code, but you need to maintain the health of your community. Pull the ban hammer on disrespectful conversation, encourage healthy debate, and continue to respond to questions.
This will help contribute to a trustworthy, respectful, and sustainable open source community.
State of the Octoverse
If you'd like to read more about the themes mentioned above, and other findings, check out the 2021 State of the Octoverse.
We'll be sharing more indepth information on each of these key themes. Keep an eye out for more.
Top comments (3)
Yet the majority of open source projects seem to get by just fine without one. Where does this idea even come from, that a project needs a code of conduct? Is there any evidence that it even does anything?
Yep, you can check out the stats on the State of the Octoverse: octoverse.github.com/
"What the data shows: The largest repositories use codes of conduct as a welcome sign... We found that the positive effects of trust and safety work in both open source and company settings, and for both small and large repositories."
Here's some good info about what a COC is good for: ethics.org/resources/free-toolkit/...
That's only a correlation though; it seems just as likely that communities that already have low tolerance for negative behaviours are also quicker to add a code of conduct.
That second link does make some good points that seem to apply mostly to businesses, but fall apart in the context of smaller open source projects, specially the legal aspect of it (which is also very specific to the USA). Most projects also just use an unmodified, widely used COC like the contributor covenant, meaning it doesn't signal anything to a would-be contributor other than a binary "has COC" vs. "has no COC".
Last but not least, a COC would be useless without a community that actively complies with it, in which case this community in itself would be a much stronger signal (think looking at code vs. looking at documentation).
Considering those points, I'm still very sceptical of the effectiveness of having a dedicated "be nice" document as part of the project. It seems more like the main reason to have one is the relatively small effort of throwing one in the repo regardless of how useful it may be.