Writing changelogs

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

Overview

The changelog is one of the few document types where the change, not the current state, is the subject; migration docs and release notes are the others. 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