Spec Versioning & Archive

What it is

Spec Versioning & Archive is w3dev's convention for the lifecycle of a spec in this registry: how the version/revision it currently follows is recorded, where its history lives, and how a spec gets retired once it's no longer followed. It fixes three mechanisms — the frontmatter version pin, an optional sibling CHANGELOG.md, and moving a retired spec into archive/ — and draws a hard line between an in-place version bump and a spec being replaced wholesale.

Why we adopted this

• One place to check "what are we following." Without a fixed pin, a spec's followed revision drifts between frontmatter, prose, and memory.
• History that outlives its links. Upstream spec pages and PRs disappear or move; a changelog entry written to be self-contained still answers "what changed and why" after the link rots.
• Specs age out instead of piling up. A retired spec should stop cluttering the current registry without losing its record.
• Bumps and rewrites are different events. Conflating "the spec issued a new revision" with "we replaced this spec with something else" makes supersedes/superseded_by and changelogs equally unreliable.

Convention

Version pin. Frontmatter version is the single source of truth for the revision or version a spec currently follows (a dated revision, e.g. MCP's 2026-07-28, or a semver string). SPEC.md describes only the current state — no version-history section in the body.

Changelog. History lives in an optional sibling specs/<slug>/CHANGELOG.md, in Keep a Changelog format. Division of labor: the story lives in the file, the diff lives in git — every entry is a self-contained human-readable summary (written as if its links might die), plus a link to the commit/PR for internal specs or the upstream dated revision for external standards. Served raw at /specs/<slug>/CHANGELOG.md; specs.json entries gain a changelog_url once the file exists. When a bump earns a detailed migration runbook, it goes in specs/<slug>/references/migration-<old>-to-<new>.md, linked from the changelog entry. Starter shape: changelog-template.md.

Archive. specs/ holds only current, followed specs. To retire one: git mv specs/<slug> archive/<slug> (archive/ mirrors the specs/ layout), set status: deprecated (plus superseded_by if something replaces it), and add a final CHANGELOG.md entry recording the retirement. Archived specs render at /archive/<slug>/ with an Archived banner; the old /specs/<slug>/ URL becomes a redirect stub, never a 404; /archive.json lists archived specs; llms.txt gains an Archive section once non-empty. The validator enforces status: deprecated only inside archive/ (never in specs/), and rejects a slug present in both trees.

Generational breaks vs. version bumps. A v2 that replaces a spec wholesale — a rewritten, incompatible contract — is a new spec id, linked to the old one via supersedes/superseded_by, not a changelog entry. An in-place revision (a new dated MCP revision, a semver bump that keeps the same contract) stays the same spec id and is logged as a CHANGELOG.md entry instead. Rule of thumb: "update this field" is a changelog entry; "adopt a different spec" is supersedes.

Links

• Keep a Changelog — the format CHANGELOG.md files follow.
• Semantic Versioning — one shape a version pin can take.
• /specs/mcp/CHANGELOG.md — worked example.
• changelog-template.md — starter template for a new spec's CHANGELOG.md.