# CONTRIBUTING.md

_Open Source · GitLab Knowledge Base_

**TL;DR:** Файл в корне репо (или в `.github/`) с правилами для контрибьюторов:
как настроить окружение, как форматировать коммиты, как присылать
PR. Чем понятнее CONTRIBUTING - тем меньше «как это запустить?» в
Issues.


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

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

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

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

```markdown
## 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. Стиль кода

```markdown
## 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](/courses/git/kb/gpg-signing.md) про pre-commit hooks
для автоматизации.

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

Часто - конвенция типа [conventional-commits](/courses/git/kb/conventional-commits.md):

```markdown
## 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

```markdown
## Pull Request process

1. Fork the repo, create a branch from `main` (see
   [upstream-vs-origin](/courses/git/kb/upstream-vs-origin.md)).
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), но иногда удобно
тут же:

```markdown
## 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
  «у меня не работает». Цикл повторяется. Обновляй вместе с
  реальными изменениями инфраструктуры.


## См. также

- [Fork vs clone](/courses/git/kb/fork-vs-clone.md)
- [Pull Request (PR)](/courses/git/kb/pull-request.md)
- [Conventional Commits](/courses/git/kb/conventional-commits.md)