Systems

Version numbers people trust

Semver is a promise about what a bump means. Changelogs are the receipt. Deprecation windows are the grace. You need all three.

Intermediate1 min read (computed · recorded 7)updated 2026-09-12semverchangelogdeprecation

by Motif Editors

revised 2026-09-12 — First publication in bank-3 batch 4.

Key takeaways

— Semver is a promise users schedule work around.
— Removals get a deprecation window: alias, warn, then remove.
— A version you can't leave is a version you'll resent.

The promise

A patch fixes without changing; a minor adds without breaking; a major does anything at all. Users plan work around that promise — CI pins, release windows, upgrade tickets. Breaking it is not a technical debt, it is a credibility debt.

The receipt and the grace

Every version gets a changelog entry in user terms (see the three questions). Every removal gets a deprecation window: alias first, warning in the output, removal one window later. The window's length is the API's usage, not your patience.

The site's changelog prints the rollback note for exactly this reason — a version you cannot leave is a version you will resent.

Practise the lesson

Theory sticks when you ship it. These original Motif assets put this guide's lesson to work — open one and copy it into your own page.

Changelog Feedpractice Changelog / Journal Templatepractice Changelog Teaserpractice

Keep learning

All guides Try the interactive Lab