How (and Why) to Build a Welcoming Open Source Community

A few friendly words of encouragement and clear guidance are sometimes all it takes to welcome someone new to an open source community.

This is true whether a new user or contributor shows up at an in-person or virtual event such as KubeCon Europe, which the AWS Open Source team attended this spring in Valencia, Spain, or in a community Slack channel, mailing list or GitHub repo as a new contributor.

At an event you might say “Welcome! We are so glad you’re here. Please take a name tag and grab a seat. We’ll get started in just a few minutes.”

Online, the best way to welcome new community members is through good documentation and good governance, according to Dawn Foster, director of open source community strategy at VMware, and Celeste Horgan, staff technical writer at Stripe, who presented talks on these topics in the open source track at KubeCon. When done well and with community involvement, these provide explicit instructions for everyone involved in a project on how to interact, contribute to and use the software. And they provide a faster on-ramp for new members looking to join and help grow the project’s contributions and sustainability over time.

“Ultimately, the focus of open source governance is on people — the roles we play, our responsibilities, how we make decisions and what we should expect from each other as part of participating,” said Foster, who is also co-chair of the Cloud Native Computing Foundation’s (CNCF) Contributor Strategy Technical Advisory Group.

For those in underrepresented groups in tech who may already feel out of place in open source software, it’s especially meaningful to be guided and welcomed by more established community members at events. Online, codes of conduct are another tool to help marginalized groups feel safe and welcome.

We heard from dozens of first-time KubeCon attendees who identify as women or non-binary about how thankful they were to be invited along for a meal, greeted warmly and introduced to others. As part of the EmpowerUS event, which AWS sponsored on the last day of KubeCon, we invited this group and their allies to fill out cards (see example above) and share their experiences with the Kubernetes and cloud native community. We learned just how much a warm and sincere welcome can affect new attendees’ feeling of acceptance and their experience of the open source community.

Open Source Governance Signals a Welcoming Community

Being welcoming means being intentional about how a project is structured and documented. This is important for attracting new code contributions and adding new features, but also for creating a culture of inclusion that makes contributors stick around for the long term, take on more responsibility and even become maintainers.

Foster and Horgan are both longtime open source contributors and experts in building communities. They gave great tips for how to structure a project in clear, methodical — and proven — ways, based on their experience growing projects from sandbox to graduation stage with the CNCF.

“A lot of people like to hate on governance as paperwork, busy work or politicking,” Foster said. “But this isn’t true of good governance. It helps get all of the people in your community aligned and collaborating together.”

A “contributor ladder” is one important part of documented open source governance that establishes the criteria and processes for moving into and out of project leadership, Foster said. When contributors know the rules and can see a clear path to becoming a maintainer, they are more likely to become maintainers, she said. This, in turn, means that as a project grows and attracts more contributors, it can avoid overloading maintainers with more and more requests that, if left unaddressed, can become a recipe for burnout, security vulnerabilities and other signs of poor project health.

Open Source Documentation Helps Communities Grow

Similarly, good documentation creates long-term sustainability and reduces maintenance issues for open source projects, Horgan said. Documentation can be an enlightening guide to previous design and architecture decisions, existing dependencies and other important details that will help new contributors to a project best consider how their own contributions will affect the project as a whole. Over the long term, as maintainers move on or relinquish their duties, those who step into leadership can refer to the documentation for instructions on how to best maintain the code and keep it reliable and secure for the many end users who rely on the critical open source projects on which their products and services are built.

While governance is best established in the early days of an open source project, documentation evolves over time, depending on the size and needs of the project. One telltale sign of a maturing open source project is when its documentation migrates from a read.me file on the project repository to its own dedicated website, Horgan said. A best practice for large projects is to welcome new contributors to participate in the documentation by identifying and scoping specific documentation issues (e.g., “we need a page with this title and subheadings x, y and z”).

“In terms of content, your biggest goal as a small project is moving from read.me’s and markdown documentation in your code repositories to a website. That is what will convince people that you’re serious enough and that this project is well maintained enough to use it,” said Horgan, who is also co-chair of the Kubernetes Special Interest Group (SIG) Docs and the Kubernetes Code of Conduct Committee.

Watch the KubeCon presentations on governance and documentation for more ideas on how to build welcoming open source communities. And come meet the AWS open source team at KubeCon North America in Detroit, Oct. 24-28!