# Contributing guide exists

- **Pattern:** `ab-000996` (`developer-documentation.getting-started.contributing-guide`)
- **Severity:** low
- **Lifecycle:** active
- **Last modified:** 2026-04-18
- **Canonical URL:** https://auditbuffet.com/patterns/ab-000996
- **License:** CC-BY-4.0 — attribute to AuditBuffet Pattern Catalog (https://auditbuffet.com/patterns/ab-000996)

## Why it matters

Without a contributing guide, the implicit message to every potential contributor is: figure it out yourself. Developers who can't run the test suite, don't know the branch naming convention, or don't understand the PR review process submit lower-quality contributions or don't contribute at all. iso-25010:2011 analysability covers this: a project is more maintainable when its development workflow is documented rather than implicit. Generic templates ('fork the repo and submit a PR') fail entirely — they don't mention how to run the actual test suite or set up the project-specific dev environment.

## Severity rationale

Low because the failure mode affects contributor throughput rather than end-user functionality, but repeated over time it compounds into a maintainability tax that stalls pull requests and discourages external participation.

## Remediation

Create `CONTRIBUTING.md` at the project root with project-specific, not generic, instructions:

```markdown
# Contributing

## Development Setup

1. Fork and clone the repo
2. Install dependencies: `npm install`
3. Copy `.env.example` to `.env` and fill in values
4. Run tests: `npm test`
5. Start dev server: `npm run dev`

## Submitting Changes

- Branch from `main`
- Write tests for new behavior
- Run `npm test` before opening a PR
- PR description must explain what changed and why
```

Replace every step above with the commands that actually work for this project. Generic templates that don't reflect the real workflow fail this check.

## Detection

- **ID:** `contributing-guide`
- **Severity:** `low`
- **What to look for:** Check for CONTRIBUTING.md at the project root or a "Contributing" section in the README. Verify it explains how to set up a local development environment, run tests, and submit changes (PR process, branch naming, commit conventions). Count all instances found and enumerate each.
- **Pass criteria:** A contributing guide exists that explains development setup, how to run tests, and how to submit changes. It is specific to the project (not a generic template). At least 1 implementation must be confirmed.
- **Fail criteria:** No contributing guide exists, or it is a generic template that doesn't mention the project's actual development workflow.
- **Skip (N/A) when:** The project is explicitly not accepting contributions (stated in README or LICENSE).
- **Detail on fail:** Example: `"No CONTRIBUTING.md and no contributing section in README"` or `"CONTRIBUTING.md is a generic template that says 'Fork the repo and submit a PR' without explaining how to set up the dev environment or run tests"`
- **Remediation:** Create CONTRIBUTING.md with project-specific instructions:

  ```markdown
  # Contributing

  ## Development Setup

  1. Fork and clone the repo
  2. Install dependencies: `npm install`
  3. Copy `.env.example` to `.env` and fill in values
  4. Run tests: `npm test`
  5. Start dev server: `npm run dev`

  ## Submitting Changes

  - Create a branch from `main`
  - Write tests for new features
  - Run `npm test` before submitting
  - Open a PR with a description of what changed and why
  ```

## External references

- iso-25010 maintainability.analysability

Taxons: code-quality

HTML version: https://auditbuffet.com/patterns/ab-000996