Git-теги, релизы и ваш changelog

Git-тег, релиз и запись changelog — три разные записи одного и того же события, и их смешивание заставляет changelog тихо отклоняться от того, что реально было выпущено. Тег отмечает коммит. Релиз упаковывает этот тег с артефактами и описанием. Запись changelog объясняет — терминами, которыми может пользоваться читательница вне репозитория — что изменилось. Обычно они происходят близко по времени, и именно поэтому легко относиться к ним как к одному шагу вместо трёх, и именно поэтому разрыв становится видимым только месяцы спустя, когда кто-то спрашивает «что вышло в v2.4», и честный ответ требует настоящих раскопок.

В чём реальная разница между этими тремя?

Тег — самая механическая из трёх: git tag v2.4.0 и готово, без требования, чтобы что-то объясняло, что в нём. Релиз добавляет описание и обычно скачиваемые артефакты, и его аудитория — всё ещё разработчицы, знающие, что такое страница релиза. Запись changelog — единственная из трёх, написанная для читательницы, которая может никогда не открыть репозиторий, поэтому именно она требует больше всего редакторского внимания и чаще всего пропускается под давлением дедлайнов.

Нужна ли каждому git-тегу запись changelog?

Нет, и относиться к ним один к одному — частая ошибка. Тег может отмечать внутреннюю веху, release candidate, или hotfix, который никогда не доходит до большинства пользовательниц; ни одному из них необязательно нужна публичная запись. Тест тот же, что решает, принадлежит ли что-то changelog вообще: заметила бы это пользовательница или вызывающая сторона, важно ли ей это. Большинство тегов проходят этот тест. Некоторые — например, тег, созданный только для запуска CI-пайплайна — никогда.

Нужен ли каждой записи changelog свой тег?

Не всегда, и здесь расходятся команды с непрерывным деплоем и команды, выпускающие версионированные пакеты. SaaS-продукт, деплоящийся несколько раз в день, может группировать несколько деплоев под одной датированной записью changelog без тега 1:1 на деплой; библиотека, публикуемая в реестре пакетов, обычно нуждается в теге на каждую опубликованную версию. Go modules и Swift Package Manager резолвят версии из самих тегов; в npm или PyPI опубликованную версию хранит реестр, а тег позволяет любому сопоставить эту версию с её исходным кодом. Репозиторию с несколькими независимо версионируемыми пакетами нужно решать это по пакету, а не один раз для всего репо; changelog монорепозитория разбирает, как префиксы тегов и область changelog должны следовать границам пакетов, а не папок. Semantic versioning и ваш changelog разбирает, как сам номер версии должен маппиться на категории changelog; теги — механизм, делающий номер версии проверяемым против реального кода.

Как описание релиза должно относиться к записи changelog?

Они могут быть одним и тем же текстом, но только если аудитория обоих действительно одна и та же, что реже, чем кажется. Страницу релиза на хостинге кода читают почти исключительно разработчицы; если у продукта есть и нетехнические пользовательницы, читающие changelog, дословное дублирование описания релиза отправляет внутренние термины и формулировки, ориентированные на код, читательнице, которой нужна была версия на простом языке. Самый чистый паттерн: писать запись changelog как основной, ориентированный на читательницу артефакт, а описанию релиза либо ссылаться на неё, либо держать более короткое, более техническое резюме для аудитории, которой уже там комфортно.

# Релиз v2.4.0 (GitHub, для разработчиц)
Поднимает пайплайн отчётов до нового движка агрегации. Смотрите
changelog для резюме, ориентированного на клиента:
https://example.com/changelog#v2.4.0

## 2026-09-07 (Changelog, ориентирован на клиента)
### Added
- Отчёты теперь загружаются меньше чем за секунду, даже для аккаунтов
  с более чем миллионом строк.

Один и тот же релиз, два документа, каждый со своей формулировкой для своей читательницы.

Откуда на самом деле берётся запись changelog?

Из двух отправных точек, и большинство реальных пайплайнов — смесь обеих. Она может генерироваться из commit-сообщений в момент тега, что быстро и никогда не пропускает смёрженный pull request; от conventional commits к changelog разбирает этот пайплайн целиком. Или она может писаться вручную, совершенно отдельно от тега, синхронизированная с моментом, когда фича считается готовой, а не с моментом, когда мёрджится код. Сгенерированные записи консистентны, но наследуют каждое расплывчатое commit-сообщение; написанные вручную — понятнее, но нужен кто-то, кто их реально напишет. Большинство команд, которые автоматизируют, всё равно оставляют лёгкий проход редактуры по сгенерированному тексту перед тем, как он станет публичной записью — та же дисциплина, что рекомендует Keep a Changelog на практике, независимо от того, откуда изначально пришёл сырой текст.

Что ломается, когда эти три расходятся?

Доверие к тому, что читательница проверила первым. Тег, существующий без соответствующей записи changelog, выглядит со стороны читательницы changelog так, будто на той неделе ничего не произошло. Запись changelog без соответствующего тега или релиза делает невозможным для того, кто отлаживает проблему в production, сделать checkout именно того кода, который был live, когда запись публиковалась. Решение — не идеальная автоматизация, а единый источник истины для этого соответствия: одно место, пусть даже это просто собственный чек-лист процесса релиза, говорящее, что выпускаемое изменение получает все три, в том же коммите или pull request, который его вводит.

FAQ

Должны ли записи changelog генерироваться автоматически из git-тегов? Они могут быть отправной точкой, но сам по себе тег не несёт никакого описания, ориентированного на читательницу — только диапазон коммитов. Автоматизированная генерация должна читать commit-сообщения внутри этого диапазона, а не просто факт существования тега, чтобы произвести что-то пригодное для использования.

Что если мы не тегируем каждый релиз? Тогда запись changelog становится основной записью, и всё равно должна нести дату и, если у продукта она есть, номер версии, чтобы запись оставалась чем-то, на что читательница может сослаться позже даже без соответствующего тега.

Должны ли pre-release-теги (вроде v2.4.0-rc.1) иметь записи changelog? В общем случае нет. Release candidate предназначен для внутреннего или бета-тестирования, и запись changelog для него учит читательниц ожидать записи для версий, которые могут никогда не выйти так, как описано. Оставляйте записи для тегов, достигающих общей доступности.

Может ли одна запись changelog покрывать несколько git-тегов? Да, и часто должна для команд, тегирующих часто. Группируйте связанные теги под одной датированной записью, описывающей чистое изменение, вместо публикации тонкой записи на тег, фрагментирующей фичу на несколько прочтений.

Технические утверждения в этой статье не проходили независимую проверку. Если здесь что-то не так, сообщите нам, и мы исправим.

По теме на changeloop: Генератор changelog, Документация для разработчиков