05 Release.ru

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

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

Порядок

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 создан, подпись владельца, запись в журнале совпадает с тегом.

Дальше

• Ловушки платформы.
• Импорт в другой агент.