Релиз-ноты на практике

Что такое changelog: определение и пример записи

5 мин чтения обновлено

Changelog представляет собой датированную запись того, что изменилось в продукте, написанная для людей, которых затрагивает изменение, а не для команды, которая его выпустила. Каждая запись называет изменение, говорит, когда оно вступило в силу, и говорит, что читательница должна с этим делать (для большинства записей это ничего). Именно последняя часть отделяет changelog от журнала коммитов: журнал коммитов пишется для тех, кто писал код, а changelog для тех, кто им пользуется.

Что такое changelog, если точнее?

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

Формат старый и намеренно простой: заголовок на релиз или на день, короткий список под ним, иногда метка категории. Keep a Changelog остаётся самой цитируемой спецификацией для этой формы (как она работает в реальном репозитории), и существует она потому, что большинство проектов, минуя спецификацию, заканчивают тем, что вываливают историю коммитов вместо неё, а это отвечает на другой вопрос, чем тот, с которым пришла читательница.

ДокументНаписан дляОтвечает на
ChangelogВсех, кто пользуется продуктомЧто изменилось, и когда?
Журнал коммитовКоманды, писавшей кодЧто сделано, в каком порядке?
Release notesПользователей, решающих обновляться лиЧто я теперь могу, чего не мог?
Patch notesИгроков или пользователей конкретного фиксаЧто именно исправил этот релиз?
RoadmapВсех, кто гадает, что дальшеЧто запланировано, и на какой стадии?

Эти пять пересекаются на практике, но это не один и тот же документ, и разница в том, кто держит его в руках в момент чтения. Changelog построен так, чтобы его искали и на него ссылались позже, поэтому его записям нужны стабильные даты и URL сильнее, чем остальным. Из этих пяти документов вперёд смотрит только roadmap; примеры product roadmap показывают шесть форматов, которые он может принимать.

Что на самом деле входит в запись changelog?

Четыре вещи, в таком порядке: что изменилось, сформулированное в терминах того, что заметил бы пользователь или вызывающая сторона; когда это вступило в силу; к какой категории относится (added, fixed, changed, removed, четыре обычные); и, когда это важно, что читательница должна с этим сделать. Ссылка на подробности допустима. Абзац внутреннего обоснования нет, потому что читательница спросила не почему, а что.

## 2026-09-07

### Added
- Счета теперь показывают налог отдельной строкой, в валюте аккаунта
  клиента.

### Fixed
- Экспорт отчёта в CSV больше не теряет последнюю строку, когда отчёт
  превышает 10 000 строк.

Эта форма масштабируется от обновления в две строки до сотни записей в релизе, не меняя структуры, и это настоящая проверка того, работает ли формат: читается ли он одинаково в загруженную неделю и в спокойную.

Есть ли шаблон changelog, который можно скопировать?

Да. Это та же форма с четырьмя распространёнными категориями, готовая для вставки в CHANGELOG.md или на страницу. Удаляйте любой заголовок, под которым в данном релизе ничего нет.

# Changelog

## 2026-10-18

### Added
- [Что пользователь теперь может, чего не мог раньше.]

### Changed
- [Что работает по-другому и что должен сделать читатель.]

### Fixed
- [Симптом, который видел пользователь и который исчез.]

### Removed
- [Что исчезло и чем пользоваться вместо этого.]

Для более длинного документа на релиз шаблон release notes добавляет строку-резюме и раздел о breaking changes. Пять готовых записей с пояснением, почему каждая работает, смотрите в примерах changelog. Если changelog живёт в репозитории, CHANGELOG.md разбирает, как держать файл актуальным, от раздела Unreleased наверху до того, что туда писать не стоит.

Кто пишет changelog, и когда?

Тот, кто внёс изменение, в момент выпуска, а не технический редактор, восстанавливающий его из тикетов неделю спустя. Тот, кто трогал код, знает, что на самом деле изменилось для пользователя; резюме, написанное задним числом, склонно описывать тикет вместо того, что реально выпустили, а это обычно шире или уже реального объёма. Некоторые команды добавляют шаг ревью перед тем, как запись станет публичной, в основном чтобы поймать просочившийся внутренний язык, и это ревью должно быть достаточно быстрым, чтобы запись вышла в тот же день.

Где место changelog?

На собственной странице, по стабильному URL, распространяемой как feed. Спрятанный в меню настроек или в теге релиза на хостинге кода, он доходит только до тех, кто уже знал, где искать. На публичную страницу можно сослаться из тикета поддержки, процитировать в обзоре или подписаться на неё. Feed важен не меньше страницы: читательница, проверяющая changelog продукта раз в месяц, редкость, а подписанная на него нет, и только feed обслуживает второй тип. Как построить публичную страницу changelog разбирает саму страницу, от URL до способов подписки.

Чем он отличается от release notes?

Их постоянно путают, и они достаточно разные, чтобы смешивание давало документ, который плохо служит обеим читательницам. Changelog против release notes разбирает различие целиком; коротко: changelog ведётся как полная, хронологическая запись, а release notes дают отобранное подмножество, написанное так, чтобы обновление звучало достойным внимания. Продукту обычно нужны оба, обращённые к разным моментам дня читательницы.

Что делает changelog стоящим прочтения?

Конкретность и честность о собственном охвате. «Разные исправления багов» учит читательницу больше не открывать страницу, потому что не обещает ничего проверяемого. Запись, называющая точное изменившееся поведение, даже для мелкого фикса, держит подписку живой. Эта дисциплина касается и того, что пропускают: changelog, объявляющий только победы и никогда не упоминающий исправление того, что было сломано, читается как маркетинг под видом changelog, и читательницы это замечают.

Дисциплина версионирования тоже важна. Semantic versioning и ваш changelog показывает, как номер версии и запись должны соответствовать друг другу, чтобы читательница, просматривая историю версий, получала один и тот же сигнал дважды, а не два разных.

Как генерируются changelog?

Двумя способами, и большинство реальных настроек представляют собой смесь. Автоматизированная генерация читает сообщения коммитов, обычно в формате Conventional Commits, и превращает их в записи без чьего-либо вмешательства в результат; от conventional commits к changelog разбирает этот пайплайн. Курируемая генерация означает, что кто-то пишет или редактирует каждую запись вручную. Автоматизированный результат быстрее и никогда не пропускает смёрженный pull request, но наследует каждое расплывчатое сообщение коммита дословно, поэтому большинство автоматизирующих команд всё равно оставляют лёгкий проход редактуры перед публикацией, а не показывают сырой результат.

На GitHub первый черновик может подготовить сама платформа: она умеет генерировать release notes из pull request’ов, смёрженных после предыдущего тега. Release notes на GitHub разбирает файл release.yml, который их группирует, и редактуру, после которой их можно читать.

FAQ

Нужен ли changelog каждому продукту? Любому продукту с пользователями, затронутыми изменениями, он нужен, будь то SaaS-приложение, внутренний инструмент или публичное API. Форма подстраивается (changelog API читается иначе, чем у потребительского приложения), потребность нет.

Что такое changelog в терминах программного обеспечения? То же определение, что и выше: датированный, хронологический список того, что изменилось в софте, написанный для тех, кто им пользуется, а не для тех, кто его строил.

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

Это то же самое, что история версий? Достаточно близко, чтобы термины использовали взаимозаменяемо. История версий иногда бывает просто списком номеров версий и дат без описания; changelog всегда включает, что изменилось.


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

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

changeloop
Команда, которая делает changelog, замыкающий цикл. Пользователи о чём-то просят, ваша команда это делает, тот, кто просил, узнаёт об этом.