changelog-discipline

CHANGELOG does not exist to duplicate version history —
version control handles that. Its job is to preserve decisions: why
this path was chosen, what was there before, what was rejected. This is exactly what
you cannot find in code.

Where it's needed

• In a project where changelog is established — after every code change.
• When first establishing changelog in a new project.
• When preparing a release.
• Not suitable for commit messages, PR descriptions, and release notes for
  users: they have different formats and readers.

Guiding principles

• The reader is "me six months from now." Context will be forgotten by then, so
  the entry must be self-contained.
• "Why" matters more than "what." "What" the diff shows; "why this was chosen" —
  nobody will show.
• A rejected alternative is gold. It protects against "improving" back to it and
  stepping on the same rake again.
• Write immediately after the change. A deferred entry degenerates into a
  diff retelling: the reason is forgotten within days.
• No exceptions. One skipped "trivial" change turns
  the log into a selective one, and selective logs cannot be trusted.

Format

File skeleton

# Changelog

All notable changes to <project>. Format — Keep a Changelog.