changelog-discipline

changelog-discipline

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

Scope

• Применять после каждого законченного изменения кода в проекте, где ведётся changelog.
• Применять при настройке changelog в новом проекте.
• Применять при подготовке релиза.
• Не применять для сообщений коммитов, описаний PR и релиз-нот для пользователей — другие форматы, другие читатели.

Core Principles

• Пишется для того, кто вернётся через полгода. Обычно это сам автор, забывший контекст.
• Полнота не требует оценки важности. Менялся код — появилась запись. Один пункт описывает цельное изменение, а не каждый файл или коммит.
• Глубина зависит от решения. Для механической правки достаточно назвать область и явно сказать, что поведение не изменилось. Для неочевидного решения нужны причина, прежнее состояние и отвергнутые варианты.
• «Почему» дороже «что». Что изменилось — видно в диффе. Почему выбрали этот вариант — не видно нигде.
• Changelog не описывает текущее состояние. Актуальное правило живёт в коде, конфигурации или контракте; changelog объясняет, почему оно изменилось, и указывает, где его искать.
• Отвергнутая альтернатива ценнее описания принятой. Она не даст через полгода переделать обратно и наступить на те же грабли.
• Запись делается сразу, а не перед релизом. Иначе полноту уже нельзя проверить по ходу работы, а причины решений успевают забыться.

Формат

Структура файла

# Changelog

Все заметные изменения <проект>. Формат — Keep a Changelog.

---

## [Unreleased]

### Added
### Changed
### Fixed

---

## [0.1.3] — 2026-07-31

### <Заголовок релиза — одной фразой о сути>

- **Что:** …
- **Где:** …
- **Почему:** …
- **Было:** …

### Added
### Changed
### Fixed

Резюме релиза — четыре поля

Самая ценная часть. Не пересказ пунктов ниже, а ответ на вопрос «что вообще поменялось в продукте»:

Поле	Что отвечает
Что	что теперь работает иначе, в терминах продукта, а не кода
Где	какие файлы и области затронуты — точка входа для того, кто полезет разбираться
Почему	какую боль это снимает; ради чего вообще делалось
Было	как вело себя до — иначе через полгода непонятно, что чинили

Поле Было чаще всего пропускают, и зря: без него запись описывает мир, которого читатель не помнит.

Пункты внутри секций

Одна запись = одно законченное изменение, а не один файл или коммит. Внутри:

• жирный заголовок — суть одной фразой
• что поменялось и где
• для механической правки — явное «поведение не изменилось»
• для неочевидного решения — почему выбрали так, как было раньше и что отвергли

Пример:

ПКМ вместо всплывающего меню по ховеру. Копирование ссылки из текста переехало в контекстное меню (LinkContextMenu). Сначала это было всплывающее по ховеру микро-меню, но до кнопки не успевал доехать курсор — контекстное меню совпадает с поведением родного текстового поля и не требует ни за чем успевать.

Здесь есть отвергнутый вариант и причина отказа. Через полгода это не даст «улучшить» обратно.

Workflow

1. После каждого законченного изменения кода — сразу дописать один пункт в [Unreleased], в подходящую секцию (Added / Changed / Fixed).
2. Выбрать глубину. Механическую правку записать одной строкой с пометкой, что поведение не изменилось. Для изменения поведения или неочевидного решения добавить причину, прежнее состояние и отвергнутые варианты.
3. Формулировать от продукта, когда поведение изменилось: не «добавил параметр», а «теперь можно X».
4. При релизе — превратить [Unreleased] в версию с датой и написать резюме из четырёх полей.

Проверка качества

Проверка полноты проста: если менялся код, в [Unreleased] появился пункт про цельное изменение.

Для механической правки достаточно ответить:

• где менялось;
• подтверждено ли, что поведение осталось прежним.

Для изменения поведения или решения запись должна отвечать:

• что изменилось для пользователя;
• почему сделали так, а не иначе;
• где смотреть код;
• как было раньше.

Если по changelog приходится восстанавливать актуальные значения или правила — они лежат не там; запись должна ссылаться на действующий источник.

References

• references/01-antipatterns.md — как не надо, с разбором
• references/02-examples.md — примеры записей до и после