This post was written by Jonas Rosland, Abigail McCarthy, and Amanda Katona.
When the VMware Tanzu Community Engagement team assembled three years ago, we did so with the belief that strong, sustainable community engagement is a crucial component of successful open source projects. With a mission of helping to build up and improve communities, we set out to support several VMware-originated open source projects.
Over the years, we have worked with many different project teams to set up solid ground rules and guidelines for how to build strong open source communities. In each project, we’ve spent time sharing community engagement principles, learning from the teams, and tailoring initiatives to what they felt comfortable doing and what would make sense both from a community and a VMware perspective, all while preserving the project's unique culture.
As we engaged with different project teams we noticed some common scenarios, and so began creating guidelines and templates consisting of straightforward, impactful practices that could help any project improve its community engagement. What started as small templates are now being used as a baseline for community engagement across many open source projects within the VMware Tanzu GitHub organization, as well as Cloud Native Computing Foundation (CNCF) projects such as Harbor, Contour, and Antrea. Continuing the open source tradition of “learn, create, and share,” we're excited to announce that we’re open sourcing our collection of community engagement guidelines and templates.
Within this repository we have collected our go-to community engagement strategy and planning guides and made them available for anyone interested in learning more about how to improve their open source projects and their community. We want this repository to be a central place to share community engagement guidelines based on our own experiences, as well as to hear feedback from you as to how these guidelines could be improved.
Now let’s dive into some of the resources we’ve made available in this new repository.
Create a solid foundation for community engagement
Regardless of whether you are starting a new open source project or are already deep into an existing one, we've learned it's never too late to create a solid foundation of resources and processes to help community members contribute. We recommend starting with the GUIDELINES.md file. It provides a checklist of project components that we’ve found essential to developing healthy community engagement within any open source project. We use these guidelines to decide on the processes and documents that will make it easier for project teams to work with open source collaborators, ensure the world knows what a project is all about, and invite community members to get started as a new user or contributor.
We feel the following components are crucial when it comes to building out a community:
-
Provide a “Getting Started” guide, one for both users and contributors
-
Make sure the documentation is up to date
-
Ensure all shared communication—recorded meetings, notes, decisions, etc.—is easy to find and readily available
-
Develop in public, using public tracking and build tools, so community members can easily follow the development of the project and build the software themselves
-
Create a project roadmap and deliver on the features set out in it
-
Engage regularly with the community on Slack, via Zoom meetings, at conferences, and other venues so as to build relationships with both your users and your contributors
These guidelines have enabled our team to quickly provide a solid foundation for open source projects of all sizes within the VMware Tanzu GitHub organization so they can easily engage with and grow their communities.
Perform health checks
The second document, HEALTHCHECKS.md, covers our process for working with project teams to understand what a healthy project looks like, give feedback on how to improve its health, and track that health over time.
As we started to get involved with more projects, we found we needed a way to measure community engagement in order to further validate and iterate on our guidelines. We wanted to steer clear of vanity metrics, such as GitHub stars and Twitter likes, because they only provide surface-level engagement information. Instead, we learned it's better to focus on metrics that provide insight into contributor satisfaction and their degree of involvement in a project over time, and that would enable us to create actionable items that project teams could use to improve the project’s overall health and help contributors become more engaged with it. The metrics we settled on include documentation quality, maintainer attentiveness, and community involvement levels, which build upon the work done by the excellent opensource.guide and the fantastic CHAOSS project.
With our health checks, we aim to
-
provide guidelines for project teams around what makes a healthy open source community experience
-
highlight areas where improvements can be made
-
spark discussion, collaboration, and the creation of new ideas to improve the community experience for everyone
-
continually evaluate projects within the ecosystem as they develop so as to allow teams the opportunity to hear about new guidelines and adjust ongoing processes
-
identify any slowdowns or lapses in projects’ progression so we can adjust accordingly
Conversely, we are not looking to
-
provide “we’re done” metrics, as open source community engagements should never be considered “done”
-
implement a pass/fail rating system for projects
-
create a single “cookie-cutter” path to be applied to every project
For projects with a dedicated community manager, we conduct these health checks every six months. We start by looking at any previous health checks and identifying what has changed since they were conducted. Even for items that were marked as being fulfilled, we measure the current status to determine if they have deteriorated or improved even further. The community manager takes a first pass, then consults with the lead maintainer to figure out if the findings correspond with their understanding of what can and needs to be improved. The health check report is then presented to the project team for further discussion so that any action items can be agreed upon.
By conducting these health checks, we’ve identified new maintainers from within the community, found and corrected issues around how decisions were made and shared, engaged in deep discussions with community members, and more.
Use inclusive terminology
As we got more involved with open source, we saw a wide range of people from across the world interacting with the software itself and within the community more broadly. One thing quickly became clear to us: To build an engaged community, we needed to make sure all contributors felt both welcomed and safe. We also realized that we could help projects create safer and more welcoming environments. And so we set out to educate ourselves on how to be more inclusive.
In our research, we learned the importance of inclusive terminology, and so began assembling a list of inclusive terminology to replace more exclusive, and harmful, word choices. Building on VMware’s own internal inclusive terminology as well as that of the Inclusive Naming Initiative, we created our own INCLUSIVE_TERMINOLOGY.md list, which includes words to avoid or substitute in projects due to their negative racial or gender connotations.
To make this list easy to apply to individual projects, we have built out an implementation of the list in Vale, a prose testing tool that can be used to check a repository’s documentation for potential violations against one or more style guides.
To use it, make sure you have Vale installed and our repo cloned, then simply run:
cd community-engagement
vale
The result could be something like:
1:1 warning Use inclusive terminology. inclusivity.inclusive-terminology
Consider "stop (v), cancel
(v), halt prematurely (v),
end prematurely (v), stop
prematurely (v)" instead of
"abort".
2:1 warning Use inclusive terminology. inclusivity.inclusive-terminology
Consider "confidence test (n),
confidence check (n)" instead
of "sanity check".
3:1 warning Use inclusive terminology. inclusivity.inclusive-terminology
Consider "(when not referring
to anything other than a
specific person) - they"
instead of "he".
3:28 warning Use inclusive terminology. inclusivity.inclusive-terminology
Consider "(when not referring
to anything other than a
specific person) - they"
instead of "she".
There are many other potential use cases in open source projects where Vale can be leveraged; we highly recommend checking out the amazing repository of styles that GitLab has put together.
You can find more content, such as our default security policy and code of conduct, in our community-engagement repo. We sincerely hope this collection of content will be useful to the open source community, and that it provides a glimpse into how the open source projects within VMware Tanzu operate when it comes to community engagement. We would also love your feedback, so if you have any suggestions or comments, please let us know in issues or pull requests!
