---
name: contributing-and-community
description: Файлы сообщества GitHub — CONTRIBUTING, CODE_OF_CONDUCT, SECURITY, SUPPORT, шаблоны issue и pull request, CITATION, GOVERNANCE, dependabot, release.yml и метрика community health. Загружать, когда репозиторий открывается для внешних участников, когда GitHub показывает неполный community profile, когда приходят неполные issue или когда нужно оформить политику безопасности и порядок приёма правок.
---

# Сообщество: файлы, которые GitHub читает

## Что проверяет GitHub

`GET /repos/{owner}/{repo}/community/profile` отдаёт `health_percentage` и список
найденных файлов. Файл ищется в нескольких местах: корень, `.github/`, `docs/`.

| Файл | Зачем | Где ищется |
|---|---|---|
| `README.md` | вход | корень, `.github/`, `docs/` |
| `LICENSE` | юридическая возможность использовать | корень |
| `CONTRIBUTING.md` | как присылать правки | корень, `.github/`, `docs/` |
| `CODE_OF_CONDUCT.md` | правила поведения | корень, `.github/`, `docs/` |
| `SECURITY.md` | как сообщить об уязвимости приватно | корень, `.github/`, `docs/` |
| `SUPPORT.md` | куда писать с вопросом | корень, `.github/`, `docs/` |
| `ISSUE_TEMPLATE/*` | структура обращений | `.github/ISSUE_TEMPLATE/` |
| `PULL_REQUEST_TEMPLATE.md` | структура правки | корень, `.github/`, `docs/` |
| `CODEOWNERS` | кто ревьюит | `.github/`, корень, `docs/` |
| `CITATION.cff` | как цитировать | корень |
| `GOVERNANCE.md` | кто принимает решения | корень, `.github/`, `docs/` |

Галочка в профиле появляется у шаблонов issue только тогда, когда они лежат **именно**
в `.github/ISSUE_TEMPLATE/` и содержат валидные ключи: `name` и `about` для markdown-
шаблонов, `name` и `description` для YAML-форм.

## Как писать CONTRIBUTING

Порядок, который работает:

1. Команды проверки — в первом же блоке кода. Не «запустите тесты», а точная команда.
2. Правила приёма: одна правка — одна причина; новое поведение с тестом; новая проверка
   с фикстурой, которая без неё падает.
3. Чего не делать: зависимости, секреты, реальные домены и адреса в примерах.
4. Как писать сообщения коммитов (Conventional Commits) и где журнал изменений.
5. Что приложить к сообщению об ошибке: версия, окружение, команда, код возврата, вывод
   без секретов.

## Как писать SECURITY

- Таблица поддерживаемых версий — первое, что смотрит читатель.
- Канал — приватный (Security → Report a vulnerability), не публичный issue.
- Что приложить и в какой срок ответ.
- Модель угроз: какие места опасны и чем защищены. Это превращает политику из формальности
  в документ, по которому можно проверить продукт.
- Чего продукт не делает (не отправляет данные, не хранит учётные данные).

## Шаблоны issue

- Форма (YAML) лучше свободного текста: обязательные поля заставляют приложить версию и
  команду.
- Три-четыре формы достаточно: ошибка, предложение, вопрос по применению, аудит.
- `config.yml` отключает пустые обращения (`blank_issues_enabled: false`) и выносит
  ссылки на политику безопасности и поддержку.

## Проверка

```bash
python <pack>/tools/ghagent.py audit .
python <pack>/tools/ghagent.py audit --repo owner/name
```

`audit` показывает, каких файлов нет (`repo.code-of-conduct`, `repo.support`,
`repo.issue-forms`, `repo.pr-template`, `repo.codeowners`, `repo.dependabot`), а
`audit --repo` — процент community health из API.

## Ловушки

| Ловушка | Признак | Что делать |
|---|---|---|
| Шаблон issue в `docs/` | галочки в профиле нет | перенести в `.github/ISSUE_TEMPLATE/` |
| YAML-форма без `description` | форма не появляется в выборе | добавить `name` и `description` |
| CODE_OF_CONDUCT без контакта | правила есть, сообщить некуда | указать приватный канал |
| SECURITY без таблицы версий | непонятно, что поддерживается | добавить таблицу |
| Политика обещает то, чего нет | заявлено, но не выполняется | писать только то, что проверяется |

## Критерий готовности

- `community/profile` — `health_percentage` не ниже 80%.
- Формы issue появляются в интерфейсе и требуют версию и команду.
- SECURITY.md содержит канал, срок ответа и модель угроз.
- CONTRIBUTING.md начинается с команд проверки, а не с благодарности.