Changelog: что это такое, с примером записи

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

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

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

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

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

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

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

## 2026-09-07

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

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

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

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

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

Где место changelog?

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

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

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

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

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

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

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

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

FAQ

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

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

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

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

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

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