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).

1. Выбрать глубину. Механическую правку записать одной строкой с пометкой,

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

1. Формулировать от продукта, когда поведение изменилось: не «добавил

параметр», а «теперь можно X».

1. При релизе — превратить [Unreleased] в версию с датой и написать резюме

из четырёх полей.

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

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

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

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

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

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

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

References

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