Skip to content

Flesh out CONTRIBUTING.md with setup, first-issue guidance, and PR conventions #6910

@compwron

Description

@compwron

Problem

CONTRIBUTING.md is currently a single line linking to the README. For a project with 340+ contributors and an active first-time contribution flow, this is the highest-leverage doc we have — and it's empty.

New contributors today have to piece together expectations from:

  • the README (setup),
  • the issue tracker (Help Wanted / Good First Issue labels),
  • past PRs (style, commit conventions),
  • ad-hoc Slack/Discord discussion.

A real CONTRIBUTING.md cuts maintainer load and unblocks people who never make it to their first PR.

Proposed sections

  1. Welcome — short paragraph, link to Code of Conduct.
  2. Getting set up — link to README setup, plus the platform-specific docs (doc/LINUX_SETUP.md, doc/MAC_SETUP.md, doc/NIX_SETUP.md, doc/DOCKER.md).
  3. Finding something to work on — point at the Good First Issue and Help Wanted labels; explain how to claim an issue (comment to claim, expected response time, what happens if abandoned).
  4. Development workflow — branch naming, how to keep your branch up to date, how to run tests and linters locally (bundle exec rspec, bundle exec standardrb, bundle exec erb_lint, npm run lint).
  5. Testing expectations — what level of coverage is expected for the change you're making (model spec, request spec, system spec).
  6. Pull request conventions — title format, what to put in the description, expectation on screenshots for UI changes, how to mark WIP vs ready (Status: WIP vs Status: Ready for Review labels).
  7. Code review — what to expect (response time, how rounds typically go, who can merge).
  8. Where to ask questions — link to Slack/Discord/issue comments.

Most of this content already exists scattered across the codebase; the work is primarily consolidation and editing rather than authoring from scratch.

Acceptance criteria

  • CONTRIBUTING.md rewritten with the sections above.
  • Internal links validated.
  • README links to CONTRIBUTING.md from a prominent spot.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    Status

    Todo

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions