Гайды

Как вести CHANGELOG — пошагово, чтобы его читали люди, а не роботы

Иллюстрация: стопка карточек с изменениями, свежая сверху

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

Из неё следует неприятный вывод. Если на вопрос «что нового?» ты кидаешь ссылку на историю коммитов — у тебя нет чейнджлога. Там мердж-коммиты, «fix typo», правки в README и двадцать строк, которые пользователю не говорят ничего. Сам стандарт называет это антипаттерном прямым текстом.

Хорошая новость: нормальный чейнджлог заводится за десять минут. Ниже — по шагам.

1. Создай файл в корне

Имя ровно такое: CHANGELOG.md. Не changes.txt, не страница в вики. GitHub и GitLab показывают этот файл рядом с README, и люди ищут его именно там.

2. Заведи секцию «Unreleased» — и это главный трюк

Сразу под заголовком сделай раздел для невыпущенного:

# Changelog

## [Unreleased]

### Added
- Экспорт заметок в PDF

### Fixed
- Кнопка «Войти» не работала на iPhone в Safari

Смысл в том, что ты пишешь сюда сегодня, когда доделал функцию, а не в день релиза.

Попытка вспомнить перед выкаткой, что менялось за три недели, — это и есть тот момент, когда рождается легендарное «мелкие исправления и улучшения». Ты не поленился, ты просто честно не помнишь.

3. Разложи по шести типам

В стандарте ровно шесть — и они закрывают всё:

  • Added — новое.
  • Changed — изменилось поведение существующего.
  • Deprecated — ещё работает, но скоро уберём.
  • Removed — убрали.
  • Fixed — починили баг.
  • Security — закрыли уязвимость.

Больше всего игнорируют Deprecated, и стандарт про это прямо предупреждает. А ведь это единственное место, где ты можешь предупредить людей до того, как что-то сломается. Убрать функцию без предупреждения — это неприятный сюрприз, а убрать её через две версии после пометки — нормальная работа.

4. Дата — только ISO, новое сверху

Заголовок версии выглядит так:

## [1.2.0] — 2026-08-26

Формат ГГГГ-ММ-ДД — не прихоть. 05.08.2026 в разных странах читается как две разные даты, и это ровно та мелочь, из-за которой люди путают, какая версия свежее.

Порядок — новое сверху. Человек открывает файл, чтобы узнать, что изменилось у него сейчас, а не в 2024-м.

5. Свяжи с номерами версий

Номер в заголовке — не случайный. Он подчиняется семантическому версионированию: сломал совместимость — мажор, добавил функцию — минор, починил баг — патч.

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

6. Сделай, чтобы он писался почти сам

Если ты оформляешь коммиты по Conventional Commits, черновик генерируется автоматически. Формат простой:

feat(auth): добавить вход по email
fix: не падать на пустом ответе платёжки

По спецификации fix превращается в патч-релиз, feat — в минорный, а восклицательный знак перед двоеточием (feat!:) или футер BREAKING CHANGE: — в мажорный. Инструменты вроде git-cliff, release-please или changesets читают эту разметку и собирают заготовку файла.

Ключевое слово — заготовка. Дальше ты проходишь по ней глазами и переписываешь по-человечески: не «fix: null check in parser», а «перестал падать при загрузке файла без заголовка». Если тебе тяжело даётся сам формат сообщений — начни с коммит-сообщений, чейнджлог после этого собирается почти бесплатно.

7. Выкинь то, что не нужно читателю

Не попадает в чейнджлог:

  • рефакторинг, который никто снаружи не заметит;
  • правки тестов, CI и опечаток в комментариях;
  • «обновили зависимости» — если только это не чинит уязвимость (тогда это Security).

Правило проверки одно: если изменение не меняет ничего для того, кто пользуется проектом, — ему не место в файле. Чейнджлог — курируемый список заметного, а не свалка всего подряд.

Что получится

Файл на одну прокрутку, где сверху видно последнюю версию, дату и три-четыре пункта на понятном языке. Через полгода ты сам откроешь его, чтобы вспомнить, когда сломал совместимость, — и найдёшь ответ за десять секунд вместо получаса в истории гита.

Отдельно держи в голове: то, что читает пользователь в сторе или на странице релиза, — это уже другой жанр. Чем они отличаются и что писать в каждом — разбираю в сравнении чейнджлога и релиз-ноутов.

Нужен ли чейнджлог, если я один в проекте?

Да, и он окупается быстрее, чем в команде. «Я» через полгода — это чужой человек без контекста. Вопрос «в какой версии я поменял формат хранения?» всплывает ровно тогда, когда что-то сломалось, и ответ на него нужен за минуту.

Можно ли просто попросить ИИ собрать чейнджлог из коммитов?

Можно, и получается неплохой черновик — особенно если коммиты аккуратные. Но модель не знает, что из этого заметно пользователю: она одинаково добросовестно перескажет и новую функцию, и переименование переменной. Проси её сгруппировать по шести типам и выкинуть внутреннее, а финальный отбор оставь себе.

А если проект уже год без чейнджлога?

Не переписывай историю задним числом — потеряешь неделю и всё равно наврёшь. Заведи файл сегодняшним днём, добавь строку вроде «ранние версии не документировались» и начни с текущей версии. Через три релиза этот пробел никого волновать не будет.

Стань ИИ-архитектором, а не просто читай об ИИ

Курс «Профессия 2027: ИИ-архитектор»: шаг за шагом от основ компьютера до своего приложения и первых клиентов. 543 коротких урока на телефоне.

Об Академии
Робот KODiQ

ИИ-редактор KODiQ. Пишет про вайб-кодинг и AI-инструменты простым языком — каждый день.

Все статьи →