In a design system that supports two major versions at once, how should its documentation be versioned, and why per major only?

## Why docs need versions A **design system** ships its components as versioned packages consumed by many product teams, and those teams upgrade at different speeds. On a music-streaming app, the phone team may already run version 4 of the component library while the smart-TV team stays on version 3 for another quarter. If the docs site shows only the latest version, the TV team reads about properties it does not have and misses guidance for ones it does. ## What semantic versioning implies Most component libraries use **semantic versioning**, a version number of the form MAJOR.MINOR.PATCH: - **MAJOR** increments for incompatible changes to the public API. - **MINOR** increments for backward-compatible new functionality — and, per the specification, when public functionality is marked deprecated. - **PATCH** increments for backward-compatible bug fixes. The specification also says the public API may be declared in the code or in documentation. For a design system, the docs are part of the contract, not just a description of it. This yields the rule: **one docs version per supported major**. Within a major, later minors are backward compatible with earlier ones, so the latest 3.x docs stay true for a team on 3.2 — as long as additions are marked with the minor that introduced them. ## One version per major, not per release | Approach | Result | |---|---| | Latest only | Teams on an older major read an API they do not have | | One per supported major | Each team reads docs valid for its version | | One per minor or patch | Dozens of near-identical copies, split search results, fixes applied to one copy and not the rest | ## How the site should behave 1. **Default to the latest major** for new readers and for search engines. 2. **Offer a version switcher** on every page that lands on the same component page in the other version when it exists. 3. **Show a clear notice** on older-major pages that a newer version exists, linking to the upgrade guide — without redirecting, since teams still on that version need the content. 4. **Mark additions inside a major** with the minor that introduced them ('added in 3.4') and deprecations with the minor that announced them, so a team on 3.2 can see what it lacks. 5. **Scope search** to the version being read, with an option to search all versions. 6. **Archive unsupported majors**: keep them reachable but visibly frozen, or retire them once no team depends on them. ## Keeping older versions correct Versioned docs are not frozen docs. While a major is supported, a mistake found in its guidance is fixed there too — an accessibility note that was wrong in version 3 is wrong for every team still on version 3. With docs as code this is natural: the older major's docs live with its maintenance line and receive fixes alongside its patch releases. What does not belong in the older docs is guidance for features that major will never get. ## Links and search engines Old versions attract traffic long after they stop being current: links pasted into tickets, bookmarks and search results. Give each version **stable, predictable addresses** (the version as part of the path), so a link to a v3 page keeps working, and tell search engines which version is the preferred one — usually the latest — so a newcomer searching for a component lands on current docs while the older page remains reachable through the switcher. ## A worked example Version 4 renames the player bar's 'compact' variant to 'mini' and removes a rarely used property. The v4 docs describe 'mini'. The v3 docs still describe 'compact', carry a notice pointing to v4 and its upgrade guide, and do not mention v4 internals. The detailed list of what changed, and why, lives in the release's change communication, which the docs link to rather than duplicate. ## Common mistakes - Redirecting every old-version page to the latest, stranding teams that cannot upgrade yet. - Publishing a separate docs copy for every minor release. - Leaving additions unmarked, so a team on an earlier minor tries a property it does not have. - Treating old-major docs as untouchable history while teams still build on them.