Writing changelogs

REQUIRED BACKGROUND: the technical-writing skill (hard rules, truth rules, style).

Overview

The changelog's subject is the change, not the current state; migration docs and release notes are the other document types with that subject. It is historical: entries are never rewritten, only appended.

When to invoke, and not

Invoke after shipping a meaningful change (a feature, a fix of real size, a removal), when writing release notes, or when summarizing what shipped. Do NOT invoke for trivial edits (roughly three changed files, or three commits), and never rewrite or delete existing entries.

Rules