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
- Welcome — short paragraph, link to Code of Conduct.
- 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).
- 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).
- 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).
- Testing expectations — what level of coverage is expected for the change you're making (model spec, request spec, system spec).
- 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).
- Code review — what to expect (response time, how rounds typically go, who can merge).
- 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
Problem
CONTRIBUTING.mdis 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:
A real CONTRIBUTING.md cuts maintainer load and unblocks people who never make it to their first PR.
Proposed sections
doc/LINUX_SETUP.md,doc/MAC_SETUP.md,doc/NIX_SETUP.md,doc/DOCKER.md).bundle exec rspec,bundle exec standardrb,bundle exec erb_lint,npm run lint).Status: WIPvsStatus: Ready for Reviewlabels).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.mdrewritten with the sections above.