changelog-discipline

Scope

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

Core Principles

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

Формат

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

# 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. Формулировать от продукта, а не от кода: не «добавил параметр в функцию», а «теперь можно X».
3. Если решение неочевидно — добавить, почему выбрано так и что отвергнуто.
4. При релизе — превратить

   [Unreleased]

   в версию с датой и написать резюме из четырёх полей.

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

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

References

• references/01-antipatterns.md

  — как не надо, с разбором

• references/02-examples.md

  — примеры записей до и после