Spec and standards changelogs: versioning a document people build against

Some of the most heavily depended-on things your team ships contain no code: the wire-protocol document two other teams implement against, the JSON Schema your partners validate uploads with, the API style guide every service is audited against, the file format you published five years ago that tools you’ve never heard of now parse. A specification is an interface whose implementations live in other people’s code — which means changing the document breaks things in repositories you can’t see, with a failure mode crueler than any API’s: nothing fails. The implementations are simply, silently, wrong now.

That’s why standards bodies — IETF, W3C, WHATWG, Unicode — treat document change management as a discipline in itself, and why your internal spec deserves a real changelog even if it’s three pages in a wiki. This guide covers the distinctions that make a spec changelog useful: normative vs editorial, errata vs amendments, living standard vs versioned snapshots, and the mechanics that keep five years of citations from rotting.

Who reads a spec’s changelog

  • Implementers, asking exactly one question: did the definition of conforming change, and do I have code to write? Every structural decision below serves this reader first.
  • Test-suite and validator maintainers. A conformance suite is a spec’s executable shadow; its maintainers need to map every behavioral change to a test change.
  • Tool authors — codegen, linters, syntax highlighters, parsers. They implement the spec’s shape, and get broken by changes you’d file as minor.
  • Citers. People who wrote “see §4.2” in code comments, contracts, audit responses, and other specs. Their links are load-bearing, and you are one careless reorganization away from breaking all of them.

The one distinction that matters: normative vs editorial

Every change to a spec is one of two things, and the changelog’s first job is to say which:

  • Editorial: wording, typo fixes, examples, formatting, reorganization. What a conforming implementation must do is untouched. Editorial changes can be rolled up — “clarified wording in §3–5, no meaning changes” — and readers with shipped code can skip them entirely.
  • Normative: the definition of conforming moved. A MUST appeared, a SHOULD became a MUST, a value range tightened, a field went from optional to required. Every normative change gets its own entry, no matter how small the diff.

The label is the reader’s triage. Without it, every implementer has to diff prose to find out whether they have work to do — so they don’t, and drift wins. And the scariest diff in this genre is the one-word “typo fix” that flips meaning: if a wording fix changes what conforming code does, it is normative, whatever the commit message says. A useful tripwire runs both directions: a normative entry with no accompanying test-suite change deserves an explanation, and an “editorial” change that forced a test update was mislabeled.

Errata vs amendments: two different confessions

Normative changes themselves split in two, and readers with shipped code care intensely about the difference:

  • An erratum says: the document failed to say what we meant. The intent never changed; the text misdescribed it. Implementers who did the intended thing have no work; implementers of the literal text do. An erratum entry must therefore say which reading was correct — “the example was wrong, the prose was right” — because both camps exist and each believes it’s the other one.
  • An amendment says: we changed our minds. The old text correctly described the old intent; the intent moved. This is a real breaking change and gets the full treatment: what changed, why, who’s affected, by when.

The IETF makes this distinction with architecture: a published RFC is immutable. Mistakes are filed as errata alongside the document, never patched into it; a change of mind requires a new RFC that formally obsoletes the old one. That’s heavier than your protocol doc needs, but the property it buys is exactly the one your citers want: a reference to the document means the same thing forever. The lightweight version is a rule, not an apparatus: never edit meaning in place — meaning changes arrive as a new dated revision with a changelog entry.

Living standard or versioned snapshots?

The other structural choice is what “a version” even is.

Versioned snapshots — W3C dated Technical Reports, JSON Schema’s date-named drafts, C++’s triennial standards, Unicode’s annual releases — give the world frozen, citable targets. Implementations claim conformance to a snapshot (“supports draft 2020-12”), test suites pin to one, and the changelog’s job is the curated diff between snapshots plus migration notes. Pick this model when conformance claims matter: procurement, regulation, certification, or an ecosystem of independent implementations that move at different speeds. The naming is calver-vs-semver all over again, with the same answer: documents rarely have compatibility surfaces clean enough for semver, which is why mature standards overwhelmingly version by date.

A living standard — the WHATWG model, where the HTML spec is simply always current — trades citability for honesty: there is one document and it describes reality now. The changelog stops being a companion and becomes the only version history there is, and citations turn date-based (“as of 2026-08-02”) — which only works if dated revisions stay reachable. Many teams land on the hybrid: a living editor’s draft that anyone can watch, plus periodic named snapshots for anyone who needs a fixed target.

Whichever model you choose, the test is the same: an implementer who last read the document eight months ago must be able to answer “what changed between what I built and what’s current?” from the changelog alone — without diffing prose or reading a commit log.

Mechanics that keep citations alive

  • Section numbers are an API. Every “see §4.2” in someone’s code review, contract, or audit response is an inbound link you can break. Give sections stable anchors that survive renumbering; if you must renumber, publish an old→new mapping in the entry, exactly as you would for a URL scheme change.
  • Diff at the keyword level. The most useful line in a spec changelog is was/now on the conformance verb: “§5.3: clients SHOULD retry → clients MUST retry.” The exact before→after numbers rule from patch notes applies to MUSTs and value ranges alike — implementers will diff you anyway; beat them to it.
  • Link the decision. Specs are arguments frozen into prose. Each normative entry should link the issue or discussion where the change was decided — rationale is to spec readers what designer notes are to players.
  • Mark the document, both directions. The changelog entry cites sections; changed sections carry a “changed in revision 14” marker pointing back at the entry — the same changed-in cross-linking that keeps docs and changelogs honest.

A revision entry template

Revision 14 — 2026-08-02

Normative changes:
- §5.3 Retry behavior: clients MUST honor Retry-After
  (was: SHOULD). Why: repeated thundering-herd incidents;
  decided in discussion #412.
  Action: clients that ignore the header are no longer
  conforming. Test retry-after-01 added to the suite.

Errata:
- §2.1: the example encoded the token as base64; the
  prose says base64url. The prose is correct — the
  example was wrong and has been fixed. Implementations
  that followed the example must switch to base64url.

Editorial (no meaning changes):
- Reworded §3–§4 for clarity; split §6.2
  into two subsections. Section numbers unchanged.

Note what the shape does: normative first and itemized, each with a was/now, a why, a link, and an action; errata that say which reading wins; editorial rolled up and explicitly harmless.

The same problem, smaller: docs sites and curated content

Content projects hit a scale model of all of this. A documentation site’s big reorganization is a URL breaking change — inbound links from blog posts, support tickets, and search results are its citations — so it ships like one: redirects for every moved page, plus a dated changelog entry saying what moved and why. A curated list or style guide earns trust the same way a spec does: additions are easy, but removals with stated reasons are what tell readers the curation is real. There’s no build pipeline in sight, and the publish-button-is-a-release rule applies: the merge is the release; date it and say what changed.

Six anti-patterns

  • The silent normative edit. Meaning changed in place, no entry, and six months later the team insists “the spec always said that.” Implementers who can prove otherwise — via archive.org, if they must — stop trusting the document entirely.
  • Unlabeled changes. A changelog that lists edits without saying normative-or-editorial makes every reader diff prose to find out if they have work. They won’t, and drift becomes the norm.
  • Renumbering without a map. Every external citation now points at the wrong section — quietly, which for a document whose whole job is precision is the worst possible way.
  • The commit-log changelog. Spec repos accumulate wording churn; mirroring it buries the three normative changes under two hundred comma commits. The unit of a spec changelog entry is a decision, not a commit.
  • The erratum that smuggles an amendment. Calling a change of mind a “clarification” to dodge the breaking-change process. Implementers of the old text know exactly what you did.
  • “It’s a living standard” as an excuse for no history. Living means the document is always current — it makes the change record more load-bearing, not less.

Running a spec changelog on Wakelog

Everything above reduces to one artifact: dated, labeled, permanent revision entries — which is what Wakelog gives a document that lives in a wiki or a git repo. Post a revision entry per meaningful change (or batch per snapshot), tag it breaking for normative changes and fix for errata so implementers can filter to exactly what affects them; the permalink becomes the stable citation for “changed in revision 14” markers, and the RSS and JSON feeds give every implementing team — and everyone who monitors specs they build against — a tripwire that fires when conformance moves. If the spec lives in git, post from CI when the revision tag lands. The honest boundary: Wakelog doesn’t host the document or diff your prose — it’s the revision history readers can subscribe to, cite, and check five years later.

Start your changelog — free   Next: docs vs changelog →

Related guides

Last updated 2026-08-02 · All guides