Scrolls
5 min read
On this page

Attracting Contributors

The number one contributor magnet is not clever marketing or conference talks. It is good documentation. People contribute to projects they can understand. If a developer cannot set up your project locally in under 30 minutes, they will move on. If they cannot figure out where the relevant code lives, they will close the tab. Every hour you invest in documentation pays for itself in contributions you would never have received otherwise.

Documentation as the First Impression

Your README is the landing page for potential contributors. It must answer five questions immediately:

1. What does this project do?        (one sentence)
2. Why should I care?                (the problem it solves)
3. How do I install it?              (copy-paste commands)
4. How do I use it?                  (minimal working example)
5. How do I contribute?              (link to CONTRIBUTING.md)

If a potential contributor has to dig through issues, blog posts, or Slack archives to understand your project, you have already lost them.

Architecture Documentation

Beyond the README, contributors need to understand the codebase structure. A brief architecture document saves dozens of "where does this code live?" questions.

Good architecture doc structure:
  /docs/architecture.md

  ## High-Level Overview
  - The project is a CLI tool that processes log files
  - Entry point: src/main.rs
  - Core parsing logic: src/parser/
  - Output formatters: src/format/

  ## Key Concepts
  - LogEntry: the main data structure, defined in src/types.rs
  - Pipeline: log entries flow through parse -> filter -> format -> output
  - Plugins: formatters implement the Formatter trait

  ## Testing
  - Unit tests live alongside source files
  - Integration tests are in tests/
  - Test fixtures are in tests/fixtures/

The CONTRIBUTING.md File

A welcoming CONTRIBUTING.md removes the friction that stops potential contributors from submitting their first PR. It should be practical, not bureaucratic.

Essential sections in CONTRIBUTING.md:

  ## Getting Started
  - Fork the repo
  - Clone your fork
  - Run: npm install
  - Run tests: npm test
  - All tests should pass on a fresh clone

  ## Development Workflow
  - Create a branch from main
  - Make your changes
  - Run the linter: npm run lint
  - Run tests: npm test
  - Submit a PR against main

  ## Code Style
  - We use Prettier with default settings
  - The linter runs automatically in CI

  ## What to Work On
  - Check issues labeled "good first issue"
  - Check the roadmap at /docs/roadmap.md
  - Feel free to open an issue to discuss before starting large changes

Projects like VS Code, Astro, and Deno maintain detailed CONTRIBUTING.md files that walk new contributors through every step, from environment setup to PR submission. The result is a steady stream of first-time contributors.

Good First Issues That Are Actually Good

The "good first issue" label is one of the most powerful contributor acquisition tools on GitHub. GitHub surfaces these issues on project profiles and in the Explore tab. But many projects misuse the label, tagging issues that require deep architectural knowledge or weeks of context.

Bad "good first issue" examples:
  - "Refactor the event system to use async iterators"
  - "Fix race condition in the connection pool"
  - "Improve performance of the query planner"

Good "good first issue" examples:
  - "Add --verbose flag to the CLI" (clear scope, touches one file)
  - "Fix typo in error message for invalid config" (trivial change, builds confidence)
  - "Add validation for negative port numbers" (small, testable, well-defined)
  - "Update dependency X from v2 to v3" (mechanical, clear success criteria)

The best good first issues share three properties. They have a clear description of what needs to change. They point to the specific file or function involved. They explain how to verify the fix works.

Writing a Good First Issue

Title: Add --json flag to the export command

## Description
The `export` command currently outputs CSV only. We want to add a
--json flag that outputs JSON instead.

## Where to Look
- The export command is in src/commands/export.rs
- Flag parsing happens in the `parse_args` function (line 42)
- Output formatting is in the `write_output` function (line 87)

## How to Test
- Run: cargo test export
- Manual test: ./tool export --json sample.db
- Expected: valid JSON array of records

## Acceptance Criteria
- [ ] --json flag is recognized
- [ ] Output is valid JSON
- [ ] Existing CSV output is unchanged
- [ ] Tests pass

Homebrew is famous for maintaining a large, well-labeled pool of good first issues. Their contributor pipeline is so effective that many developers get their first open source contribution through Homebrew.

Fast PR Reviews

Nothing kills contributor motivation faster than a PR that sits unreviewed for weeks. The signal it sends is clear: your time does not matter to us.

PR review response times and their effects:

  < 24 hours:  Contributor feels valued. Likely to contribute again.
  2-3 days:    Acceptable. Contributor stays engaged.
  1 week:      Contributor loses context. May need to re-learn what they did.
  2+ weeks:    Contributor has moved on. PR may become stale and unmergeable.
  1+ month:    Contributor will never come back. Tells others the project is dead.

You do not need to do a full review in 24 hours. An initial acknowledgment matters more than a final approval. A comment like "Thanks for this PR. I will review it fully by Thursday" keeps the contributor engaged.

React, Kubernetes, and Rust all maintain review SLAs, either formally or culturally. The Rust project aims to respond to all PRs within a week, and most get an initial response within 48 hours.

Public Roadmap

A public roadmap tells potential contributors where the project is going and where help is needed. Without one, contributors must guess what the maintainers want.

Roadmap formats that work:

  GitHub Project Board:
    - Columns: Planned, In Progress, Done
    - Each card links to an issue
    - Labeled by priority and area

  Roadmap document (/docs/roadmap.md):
    ## v3.0 (Target: Q3 2026)
    - [ ] Plugin system (issue #234) — looking for contributors
    - [ ] Windows support (issue #189) — in progress
    - [ ] Performance overhaul (issue #301) — needs design discussion

    ## v3.1 (Target: Q4 2026)
    - [ ] GUI tool (issue #350) — open for proposals
    - [ ] Wasm support (issue #412) — blocked on upstream

Tauri, Remix, and Biome maintain public roadmaps that explicitly mark items where contributors can help. This turns passive users into active contributors because they can see exactly where to plug in.

The Contributor Funnel

Contributor growth follows a funnel, similar to product user acquisition. Each stage requires intentional effort to move people to the next level.

The contributor funnel:

  User
    Someone who uses your project. They found it, installed it, and it works.
    How many: thousands

  Issue Reporter
    A user who cared enough to file a bug or request a feature.
    How many: hundreds
    How to convert: make filing issues easy, use issue templates,
    respond to issues quickly

  First-Time Contributor
    An issue reporter who submitted a PR. This is the hardest conversion.
    How many: dozens
    How to convert: good first issues, welcoming CONTRIBUTING.md,
    fast PR reviews, kind code review comments

  Regular Contributor
    Someone who has submitted multiple PRs over time.
    How many: a handful
    How to convert: give them ownership of a feature area,
    invite them to contributor meetings, recognize their work publicly

  Maintainer
    A trusted contributor with merge access and decision-making authority.
    How many: 2-5
    How to convert: gradually increase responsibility, add them as
    a code owner for their area, formalize the role

Node.js grew its contributor base deliberately through this model. They created a "Collaborator" role between contributor and core maintainer, making the path to deeper involvement visible and achievable.

Recognizing Contributors

Recognition keeps contributors coming back. It costs nothing and pays dividends.

Recognition methods:
  - Mention contributors in release notes
  - Use the all-contributors bot to add faces to the README
  - Thank first-time contributors publicly in the PR
  - Write a blog post highlighting community contributions
  - Give top contributors a shoutout at conferences
  - Add a CONTRIBUTORS file or an AUTHORS section

Astro publishes a "Community Day" blog post each month highlighting contributions. Next.js mentions contributors by name in release notes. These small gestures build loyalty and encourage repeat contributions.

Common Pitfalls

  • Documentation that only serves existing maintainers. Your docs need to serve someone who has never seen the codebase. If your setup instructions assume knowledge of your custom build system, new contributors cannot even start.

  • "Good first issue" labels on hard problems. A contributor picks up what looks like a simple issue, struggles for hours, and gives up feeling incompetent. They blame themselves, not your labeling. You lose a potential contributor forever.

  • Slow or harsh code reviews. Leaving a wall of nitpicks on a first-time contributor's PR teaches them to never come back. Save the style discussions for regulars. For new contributors, focus on whether the code works and fix minor issues yourself.

  • No clear path beyond the first contribution. Many projects are good at attracting first-time contributors but have no pipeline for converting them into regulars. Without explicit next steps, one-time contributors stay one-time.

  • Expecting gratitude. Contributors are volunteering their time. They do not owe you anything. If they submit a PR and disappear, that is normal. Do not guilt-trip or publicly shame inactive contributors.

Key Takeaways

  • Good documentation is the single most effective way to attract contributors. If people cannot understand your project, they cannot contribute to it.
  • A welcoming CONTRIBUTING.md with clear setup instructions removes the primary barrier to first contributions.
  • "Good first issue" labels must point to genuinely small, well-scoped tasks with clear instructions. Mislabeled issues drive contributors away.
  • Fast PR reviews signal that contributor time is valued. Aim for initial acknowledgment within 48 hours.
  • A public roadmap shows contributors where help is needed and gives them a clear place to plug in.
  • Contributor growth follows a funnel from user to maintainer. Each transition requires intentional effort and different tactics.