CONTRIBUTING.md

CONTRIBUTING.md - это «инструкция для тех, кто хочет помочь». Не README (что это за проект), а отдельный документ про процесс работы с кодом.

Хороший CONTRIBUTING экономит часы майнтейнерам: вместо объяснений в каждом Issue они отправляют по ссылке.

Минимальное содержание

1. Как поднять локально

## Local setup

1. `git clone git@github.com:foo/bar.git`

2. `cd bar`

3. `make install` (or `npm install`)

4. `make test` to verify the setup

Requires: Python 3.11+, Docker.

Без этого новичок час разбирается, что вообще делать. Желательно тестировать инструкцию на свежей машине раз в полгода - обычно она устаревает.

2. Стиль кода

## Code style

- Run `make fmt` before committing - uses `ruff format` and

  `prettier`.

- Run `make lint` to catch issues.

- Tests must be in `tests/`, mirror module structure.

Лучше, чем 50-страничный style guide: одна-две команды, которые делают всё автоматически. См. gpg-signing про pre-commit hooks для автоматизации.

3. Формат коммитов

Часто - конвенция типа conventional-commits:

## Commit messages

We use Conventional Commits:

- `feat: add user login`

- `fix: handle null in pagination`

- `docs: update README`

- `refactor: extract helper`

Reference issue: `fix: timeout (#123)`.

Без явного указания формата каждый PR - это разнобой стилей. С явным - единая история и автогенерируемые CHANGELOG.

4. Процесс PR

## Pull Request process

1. Fork the repo, create a branch from `main` (see

   [[upstream-vs-origin]]).

2. Make your changes; keep PRs focused on one thing.

3. Run `make test` locally - CI also runs it.

4. Open a PR with description: what changed, why, what was tested.

5. Address review comments; maintainer merges when approved.

Не «PR - это легко, делайте что хотите», а конкретный workflow, чтобы не было «зачем squash?» в момент мержа.

5. Как сообщить о баге / попросить фичу

Часто этого нет в CONTRIBUTING (это про Issues), но иногда удобно тут же:

## Reporting bugs

Use the «Bug report» Issue template. Include:

- what you did,

- what you expected,

- what happened,

- your environment (OS, version, ...).

## Feature requests

Open a Discussion before a PR. We may already have plans.

6. Code of Conduct (опционально)

Для проектов с большим community обычно отдельный файл CODE_OF_CONDUCT.md или ссылка в CONTRIBUTING. Часто - Contributor Covenant.

Чего НЕ нужно

• Не пиши «следуй существующему стилю, спрашивай». Это нечитаемо. Конкретные команды/правила.
  • Не дублируй README. В CONTRIBUTING - про процесс (как контрибьютить), в README - про что (что это, как использовать).
  • Не делай CONTRIBUTING длиннее 200 строк. Если больше - разбивай на отдельные документы (docs/dev-setup.md, docs/release-process.md).

Где лежит

Три варианта (GitHub понимает все):

1. CONTRIBUTING.md в корне. Очевидно, видно сразу при clone.
2. .github/CONTRIBUTING.md. Если корень и так перегружен.
3. docs/CONTRIBUTING.md. Если есть отдельная docs/ ветка.

При создании Issue или PR на GitHub в правой колонке появится ссылка «Read CONTRIBUTING guide» - это работает только если файл лежит в одной из трёх стандартных позиций.

Подводные камни

• «Pull requests welcome» в README, и пусто в CONTRIBUTING - обещание без инструкций. Новичок начинает PR без понимания процесса, делает не так, фрустрируется. Хуже, чем «contributions closed».
• CONTRIBUTING противоречит README. В README сказано «требуется Docker», в CONTRIBUTING - «нужен local Python». Раз в полгода проходить - синхронизировать.
• CONTRIBUTING устарел. Указано make install, а в проекте давно pnpm install. Контрибьютор тратит час, пишет в Issue «у меня не работает». Цикл повторяется. Обновляй вместе с реальными изменениями инфраструктуры.