Как вести 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 коротких урока на телефоне.





