---
title: The inequity of contributing guides
description: Your CONTRIBUTING.md isn't welcoming. It's a gatekeeping document. Most open source contribution guides exclude the people they claim to want.
canonical: https://lukeocodes.dev/the-inequity-of-contributing-guides
type: article
locale: en_GB
published: 2026-05-28T00:00:00.000Z
modified: 2026-05-28T00:00:00.000Z
authors:
  - Luke Oliff
section: Opinion
tags:
  - Opinion
feed: https://lukeocodes.dev/rss.xml
search: https://lukeocodes.dev/search.json?q={query}
schema:
  - "@context": https://schema.org
    "@graph":
      - "@type": Organization
        "@id": https://ably.com/#organization
        name: Ably
        url: https://ably.com
      - "@type": WebSite
        "@id": https://lukeocodes.dev/#website
        url: https://lukeocodes.dev
        name: Luke Oliff
        alternateName: lukeocodes
        inLanguage: en
        publisher:
          "@id": https://lukeocodes.dev/authors/luke#person
        description: Personal blog and writing by Luke Oliff — developer relations, voice AI, developer experience.
        potentialAction:
          - "@type": SearchAction
            target:
              "@type": EntryPoint
              urlTemplate: https://lukeocodes.dev/blog/search?q={search_term_string}
            query-input: required name=search_term_string
      - "@type": Person
        "@id": https://lukeocodes.dev/authors/luke#person
        name: Luke Oliff
        url: https://lukeocodes.dev/authors/luke
        description: Staff engineer and Staff Tech Lead for Developer Experience at Ably. Writing about developer relations, AI, and the voice industry, from the UK.
        mainEntityOfPage: https://lukeocodes.dev/authors/luke
        givenName: Luke
        familyName: Oliff
        image: https://lukeocodes.dev/authors/luke.jpg
        jobTitle: Staff Tech Lead, Developer Experience
        worksFor:
          "@id": https://ably.com/#organization
        sameAs:
          - https://www.linkedin.com/in/lukeocodes
          - https://github.com/lukeocodes
          - https://bsky.app/profile/lukeocodes.dev
          - https://x.com/lukeocodes
          - https://hashnode.com/@lukeocodes
          - https://dev.to/lukeocodes
        knowsAbout:
          - Developer Relations
          - Developer Experience
          - Voice AI
          - Text-to-Speech
          - Answer Engine Optimisation
          - Search Engine Optimisation
          - Open Source
          - Developer Tooling
          - API Design
          - Speech-to-Text
          - Voice Agents
          - Community Building
        knowsLanguage:
          - English
        nationality: British
        alumniOf:
          - "@type": Organization
            name: The Open University
  - "@context": https://schema.org
    "@graph":
      - "@type": Organization
        "@id": https://ably.com/#organization
        name: Ably
        url: https://ably.com
      - "@type": Person
        "@id": https://lukeocodes.dev/authors/luke#person
        name: Luke Oliff
        url: https://lukeocodes.dev/authors/luke
        description: Staff engineer and Staff Tech Lead for Developer Experience at Ably. Writing about developer relations, AI, and the voice industry, from the UK.
        mainEntityOfPage: https://lukeocodes.dev/authors/luke
        givenName: Luke
        familyName: Oliff
        image: https://lukeocodes.dev/authors/luke.jpg
        jobTitle: Staff Tech Lead, Developer Experience
        worksFor:
          "@id": https://ably.com/#organization
        sameAs:
          - https://www.linkedin.com/in/lukeocodes
          - https://github.com/lukeocodes
          - https://bsky.app/profile/lukeocodes.dev
          - https://x.com/lukeocodes
          - https://hashnode.com/@lukeocodes
          - https://dev.to/lukeocodes
        knowsAbout:
          - Developer Relations
          - Developer Experience
          - Voice AI
          - Text-to-Speech
          - Answer Engine Optimisation
          - Search Engine Optimisation
          - Open Source
          - Developer Tooling
          - API Design
          - Speech-to-Text
          - Voice Agents
          - Community Building
        knowsLanguage:
          - English
        nationality: British
        alumniOf:
          - "@type": Organization
            name: The Open University
      - "@type": BlogPosting
        "@id": https://lukeocodes.dev/the-inequity-of-contributing-guides#article
        headline: The inequity of contributing guides
        alternativeHeadline: The inequity of contributing guides
        description: Your CONTRIBUTING.md isn't welcoming. It's a gatekeeping document. Most open source contribution guides exclude the people they claim to want.
        datePublished: 2026-05-28T00:00:00.000Z
        dateModified: 2026-05-28T00:00:00.000Z
        url: https://lukeocodes.dev/the-inequity-of-contributing-guides
        mainEntityOfPage: https://lukeocodes.dev/the-inequity-of-contributing-guides
        inLanguage: en
        author:
          - "@id": https://lukeocodes.dev/authors/luke#person
        isPartOf:
          "@id": https://lukeocodes.dev/#website
        keywords: Opinion
        articleSection: Opinion
        abstract: Your CONTRIBUTING.md isn't welcoming. It's a gatekeeping document. Most open source projects have a contribution guide.
        speakable:
          "@type": SpeakableSpecification
          cssSelector:
            - .post-tldr
            - h1
        image: https://lukeocodes.dev/og.png?h=The+inequity+of+contributing+guides&d=Your+CONTRIBUTING.md+isn%27t+welcoming.+It%27s+a+gatekeeping+document.+Most+open+source+contribution+guides+exclude+the+people+they+claim+to+want.&e=Writing
        wordCount: 585
        timeRequired: PT3M
        publisher:
          "@id": https://ably.com/#organization
      - "@type": BreadcrumbList
        itemListElement:
          - "@type": ListItem
            position: 1
            name: Home
            item: https://lukeocodes.dev
          - "@type": ListItem
            position: 2
            name: Writing
            item: https://lukeocodes.dev/blog
          - "@type": ListItem
            position: 3
            name: The inequity of contributing guides
            item: https://lukeocodes.dev/the-inequity-of-contributing-guides
---

[Luke Oliff.](/)

- [Blog](/blog)
- [CV](/cv)
- [Uses](/uses)
- [User manual](/user-manual)
- [Living with ADHD](/living-and-working-with-adhd)
- [RSS](/rss.xml)

[Luke Oliff · Writing](/blog)

# The inequity of contributing guides

May 2026 · [Opinion](/blog/category/opinion) · 3 min read · [Luke Oliff](/authors/luke)

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.

[← Newer: Friday fun: my .zshrc has more aliases than I have memory](/my-zshrc-has-more-aliases)

[All posts](/blog) →

## Search this site

`GET https://lukeocodes.dev/search.json?q=<words>` returns matching posts as JSON, each with its page URL and its markdown URL. Add `&limit=<1-50>` for more than 10. How it works: [/blog/search](https://lukeocodes.dev/blog/search.md).

```sh
curl "https://lukeocodes.dev/search.json?q=developer+relations"
```

---

© 2026 Luke Oliff. Posts live at the root of this site.

- [GitHub](https://github.com/lukeocodes)
- [LinkedIn](https://www.linkedin.com/in/lukeocodes)
- [X](https://x.com/lukeocodes)
- [Bluesky](https://bsky.app/profile/lukeocodes.dev)
- [Email](mailto:luke@lukeoliff.com)
- [RSS](/rss.xml)

## Cookies

This site sets one analytics cookie, from Google Analytics, and only in a browser that accepts the cookie banner. A client that does not run scripts sets no cookies, so there is nothing to accept or decline here.

[Cookie policy](/cookies)
