# Выпуск версии

Выпуск — это не только тег. Это запись в журнале, дата, ссылки сравнения и текст релиза,
которые совпадают между собой.

## Порядок

```bash
python tools/ghagent.py changelog check
python tools/ghagent.py changelog suggest --since v1.1.0
python tools/ghagent.py changelog release 1.2.0 --write
python tools/ghagent.py changelog check
python tools/ghagent.py changelog notes 1.2.0 > release-body.md
gh release create v1.2.0 --notes-file release-body.md --title v1.2.0
```

## Что делает `release`

| Шаг | Результат |
|---|---|
| Проверяет версию | отказ, если версия не SemVer или уже существует |
| Проверяет `[Unreleased]` | отказ, если записей нет |
| Переносит разделы | `[Unreleased]` снова пустой, новая версия с датой |
| Обновляет ссылки | `[Unreleased]: …/compare/v1.2.0...HEAD`, `[1.2.0]: …/compare/v1.1.0...v1.2.0` |
| Перепроверяет файл | ошибки печатаются сразу, а не через неделю |

Без `--write` команда только показывает, что изменится.

## Выбор номера версии

| Изменение | Номер |
|---|---|
| исправление | патч `1.2.3 → 1.2.4` |
| новая возможность, совместимая | минор `1.2.3 → 1.3.0` |
| ломающее изменение | мажор `1.2.3 → 2.0.0` |
| проект до `1.0.0` | `0.y.z`: минор может ломать, и это пишется явно |

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

| Плохо | Хорошо |
|---|---|
| `fix: off-by-one in ExpiryCalculator` | «счётчик дней до оплаты больше не ошибается на сутки» |
| `refactor` | «синхронизация выполняется одним запросом вместо трёх» |
| «разные улучшения» | три отдельные записи с наблюдаемым следствием |
| «breaking change» отдельным разделом | `**Breaking:**` в самой записи раздела `Changed` |

Запись адресована пользователю: он должен понять, что изменилось в его работе, без чтения
кода.

## Ловушки

| Ловушка | Признак | Что делать |
|---|---|---|
| Журнал из лога коммитов | записи `Merge pull request #12` | писать заново по-человечески |
| Версия без даты | `## [1.2.0]` | `release` ставит дату сам |
| Две записи об одной версии | `changelog.duplicate` | объединить |
| Забытая ссылка сравнения | `[1.2.0]` не открывается | `release` добавляет её сам |
| Тег без заметок | релиз пустой | `changelog notes` даёт текст |

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

- `changelog check` — код `0`.
- `changelog notes` даёт текст, который можно отправлять как есть.
- Тег `vX.Y.Z` создан, подпись владельца, запись в журнале совпадает с тегом.

## Дальше

- [Ловушки платформы](06-Traps.ru).
- [Импорт в другой агент](07-Import.ru).