In open source communities, we often discuss contribution guidelines, codes of conduct, and onboarding new contributors. But one thing we don’t talk about nearly enough? Governance.
Governance sounds serious. But at its core, it simply means: how do we make decisions, and who gets to make them? It doesn’t matter if you’re working on a project at the grassroots level with a few maintainers or a mature open-source ecosystem – the guiding procedures influence how people contribute, manage issues, and develop into leaders.
And, like with anything in open source – if it isn’t documented, it may as well not exist.
In this article, I’ll explain why governance documentation is important, what to include, and how to document governing procedures that are useful, clear, and human.
Table of Contents
Why Governance Matters (and Why You Should Document It)
Every open-source community already has some kind of governance (even if it’s not written down). Sometimes it’s a single maintainer making all decisions. Sometimes it’s a small group of people “just knowing what’s best.” The danger here is not the structure itself but the lack of clarity around it.
When governing procedures aren’t documented:
-
New contributors might be confused about how to get involved
-
Decisions appear arbitrary or biased
-
Power dynamics become invisible
-
Conflict becomes harder to manage or resolve fairly
Documenting governance promotes trust, transparency, and predictability. It does not imply confining contributors to rigid rules – rather, it offers your community a common understanding of how things work and how they may change.
What Your Governance Documentation Should Have
You don’t need to start governance documentation from scratch. You probably already have fragments of governance in your README, CONTRIBUTING.md, or pinned messages in your community’s messaging platform. The goal is to bring them together into something clear, navigable, and contributor-friendly.
Think of your governance documentation as a map. It should help contributors understand where they are, how things work, and what paths they can take, including:
-
Mission and Values: Why does this project exist? What principles guide how decisions are made or prioritised? This can set the tone for governance and invite collaboration.
-
Roles and Responsibilities: Who are the maintainers? What can contributors, reviewers, and core team members do? Who can open pull requests? Review them? Approve proposals? Define expectations and boundaries clearly.
-
Decision-Making Process: How are technical decisions made? By consensus? By voting? Is there a lead maintainer with the final say? What types of decisions require community input? How are disputes resolved?
-
Conflict Resolution: What happens if people disagree? Is there a process to escalate issues respectfully?
-
Proposal Process: How are changes proposed and discussed? Do you use an RFC system, GitHub discussions, or something else? What’s the typical timeline for review or feedback?
-
Leadership Changes: How are new maintainers added? How can someone step down or be removed?
-
Amending Governance: How can the governing procedure itself and its documentation be changed? Who has the authority to do so?
-
Contributing Guidelines: How can contributors get started? How can they submit a pull request? What does review and approval look like? Is there a contributor ladder? What happens after someone contributes regularly? Make it easy for everyone to get around the overall contributor experience
-
Code of Conduct (linked or embedded): Governance and conduct are deeply connected. One shapes the culture, while the other protects it.
Make Governing Documentation Clear and Welcoming
Governance documentation doesn’t have to read like legal policy. In fact, it shouldn’t. A clear, welcoming tone helps readers feel included, especially newcomers or contributors from under-represented groups.
The tone you use in your governance docs will shape how people feel about your community. It can either feel like a locked gate or a clear, friendly path forward. Here’s how to keep them human:
-
Use plain, clear language. Avoid overly complex terms, and explain acronyms if needed.
-
Be specific. “You must be in the Discord server to vote” is better than “participation is required.”
-
Keep it short and easy to read. Use lists, headings, and bullet points.
-
Explain the “why.” Give more context. People are more likely to trust rules when they understand why they exist.
-
Use examples or scenarios. For example, “when two maintainers disagree on a technical direction…”
-
Make it feel open. Invite contributors to ask questions or suggest changes, including to governing procedures. That alone can help your community evolve with less friction.
How to Start Documenting Governing Procedures for Your Open Source Community
I’ve helped document governance in projects where things had been informal for years. The hardest part? Starting. There’s always a fear of overstepping or “making it too official.”
But writing things down doesn’t have to mean locking them in stone. In fact, the best governance docs are living documents, created with the community, reviewed regularly, and updated as the project grows.
Some lessons I’ve learnt:
-
Start small. Even a bulleted list in a README is better than nothing.
-
Use your community’s questions as your guide. If people keep asking, “how do I become a maintainer?” write that down.
-
Let people review and comment. Co-create – don’t just impose.
If you’re not sure where to begin, look to open-source projects that have done this well. For example, Kubernetes has a well-structured governance model documented in its community repository, outlining everything from roles to decision-making processes.
The Tor Project also maintains transparent and community-driven governance documentation (a project I had the opportunity to contribute to) that defines roles, responsibilities, and decision-making pathways that are communicated to contributors all over the world.
Conclusion
Documenting governance doesn’t have to be scary. It’s just about making the invisible visible and doing it in a way that invites people in. When you write down how things work, you make space for others to contribute confidently, understand the community they’re joining, and grow within it. That’s what governance should be about.
So if your project doesn’t have its governing principles documented yet, don’t wait for it to get “big enough.” Start now, start small, and let it evolve with your community.
And remember: governance isn’t about control. It’s about clarity.
Source: freeCodeCamp Programming Tutorials: Python, JavaScript, Git & MoreÂ
