contributing-conventions

Files (1)

• SKILL.md

SKILL.md (first lines)

# CONTRIBUTING conventions

A `CONTRIBUTING.md` answers one question: **"I want to change this code — how
do I get a working setup and land a green PR?"** It is the *contributor's*
counterpart to the README's *user* view, and it is linked from the README (see
`readme-conventions`).

Keep it operational: commands, not philosophy — and in English
(`documentation-conventions`).

## Mandatory structure

```markdown
# Contributing

<One or two sentences: how to reach the maintainers, and the short version.>

## Development setup

## Running the tests

## Pre-commit hooks

## Continuous integration

## Submitting a change

## Releasing
```

`Releasing` only when the project cuts releases; every other section is
mandatory.

### 1. Development setup — what to install

Everything a contributor needs that a *user* does not. The README covers
running the project; this covers building on it.

- **List the tooling**, and how to get it — the toolchain (`rustup`, `uv`,
  `node`), the package manager, `pre-commit` itself, and any binary the hooks
  or tests shell out to (`sqlfluff`, `helm`, `terraform`, `hadolint`,
  `trivy`). If a hook needs a binary that isn't installed, the contributor
  discovers it as a cryptic failure — list it here instead. **Link the file
  that pins a version** (`rust-toolchain.toml`, `.python-version`, a hook's
  `rev`) rather than copying the number; write one only when nothing in the
  repo pins it (`pre-commit` 4.x).
- **Give the bootstrap as a copy-pasteable sequence**, in order, from a fresh
  clone:

  ```bash
  uv sync --all-extras
  ```

  ```bash
  pre-commit install
  ```

  One command per fenced block, no `$` prompt, no interleaved output.
- **Every install command covers macOS *and* Linux** — `readme-conventions`
  carries the rule and the example.
- **Say what "it works" looks like** — the one command that proves the setup
  is good, and point at the test section below for the rest.
- **Do not restate the README.** How to *run* the project, its environment
  variables, its config — those live in the README. Link to it:
  `See [README.md](README.md#getting-started) for running the project.`
- Mention the editor/LSP setup only when it is genuinely required (a
  `pyrightconfig.json`, a rust-analyzer setting the code depends on), never as
  a list of the maintainer's favourite plugins.

### 2. Running the tests

**The test commands live here, not in the README** — running the suite is a
contributor's loop, not a user's. Give them verbatim, from the repo's actual
tooling:

- **The whole suite**, the one command that must be green before a PR:

  ```bash
  uv run pytest
  ```

- **A subset**, because nobody runs the full suite on every save — a single
  file, a single test, a marker or feature flag:

  ```bash
  uv run pytest tests/test_parser.py::test_rejects_empty_input
  ```

- **The categories that exist and how they differ** — unit vs integration vs
  end-to-end — and crucially **what each one needs**: a running database, a
  cluster, a container runtime, credentials for a sandbox account. A test
  suite that silently requires Docker is a contributor's lost afternoon.
- **How to run the slow or optional ones**, and how they're excluded by
  default (a marker, a feature, an environment variable).
- **Coverage**, only if the project actually enforces a threshold — the
  command and the number. Don't document a coverage tool nobody gates on.
- **What is expected of a new change**: tests for new behaviour, a regression
  test for a fix. Say it once, here.

If a test needs fixtures, seed data, or a `docker compose up` first, that
command belongs in this section too — a contributor should never have to
reverse-engineer a failing test to discover it needed a service.

### 3. Pre-commit — the gate

Every repo has a `.pre-commit-config.yaml` with the baseline hooks and those
for each technology in use (`pre-commit-conventions`); this section is how a
contributor lives with it.

- **`pre-commit install` is part of the setup**, and say plainly that hooks
  must pass before a commit is pushed.
- **Give the two commands**: the whole repo, and re-running a single hook
  while iterating.

  ```bash
  pre-commit run --all-files
  ```

  ```bash

From leroyguillaume/claude, MIT.

More from leroyguillaume/claude