The inequity of contributing guides

Your CONTRIBUTING.md isn’t welcoming. It’s a gatekeeping document.Most open source projects have a contribution guide.

Most of them think it makes their project more welcoming. Most of them are wrong.

I’ve spent years in Developer Experience and the uncomfortable truth is that a CONTRIBUTING.md written by maintainers, for maintainers, almost never serves the people it’s supposed to be for.

What actually happens: someone builds something, gets deep into the codebase, and eventually writes down the process that already lives in their head. The result isn’t a welcome mat. It’s insider knowledge dressed up as documentation.

The people who find it easiest to follow are the people who already fit. Same professional background. Same Git etiquette absorbed from years in industry. Same instinct for what a “good PR” looks like. Same time and energy to go back and forth on review feedback for a contribution they’re doing for free.

Everyone else just hits a wall they can’t see.

I think we’ve got the whole thing backwards.

Internal process should be concrete. External process should be flexible.

If commit message format matters, automate it. If test coverage is non-negotiable, put it in CI. Let machines do the gatekeeping - they’re consistent, they don’t have unconscious bias, and they give the same feedback to everyone.

The human-facing side should be a conversation, not a compliance checklist.

The moment your contribution guide starts reading like a legal document, you’ve optimised for the people who already know how this works - and made it harder, quietly and invisibly, for everyone else.

What a more equitable contribution experience actually looks like:

If it can be a linter rule or a CI gate, it should be. Get humans out of policing style.

Say something like “if any of this is confusing, that’s a bug in the guide - tell us.” It’s a small thing but it completely flips who carries the burden.

If your guide only describes code PRs, you’ve already told non-engineers they’re not welcome. Docs, triage, accessibility review, translation - name them or they don’t exist.

And make your review process legible. A PR that stalls without explanation is disproportionately discouraging for people who already feel like outsiders. Saying “we’re slow on reviews right now” isn’t weakness, it’s just decent.

The real problem is that process accumulates.

Projects start small. The maintainers know each other. Contributions flow through trust and shared context. Then the project grows and someone writes down the unspoken rules - and suddenly those rules are the bar everyone has to clear.

The demographics of open source aren’t an accident. They’re what happens when processes get optimised, over and over, for the people already in the room.

A contribution guide isn’t neutral. It’s a set of choices about who finds it easy to show up.

Worth being intentional about.

FAQ

Why are traditional contributing guides problematic?

Most CONTRIBUTING.md files are written by maintainers based on their own internalized processes. Instead of welcoming new contributors, they often act as gatekeeping documents that heavily favor people with the same professional background, neurotype, or free time. They turn contribution into a compliance checklist rather than a collaborative process.

How can maintainers make their projects more inclusive?

Automate the gatekeeping. If commit formats, linting, or test coverage are non-negotiable, use CI/CD pipelines to enforce them consistently and without bias. The human-facing documentation should focus on the “why” and “where,” offering flexibility and opening a conversation rather than presenting a rigid list of rules that discourage diverse contributors.