skip to content

In a component library preparing a breaking major release, how should the team use semantic-versioning pre-releases to let consuming teams trial it?

level: middleimportance: should knowfreq 30%

answer

  1. a hyphenated label after the patch
  2. sorts below the final release
  3. no compatibility promise between betas
  4. pilots opt in explicitly
  5. never the default install

basics

~10 s

Publish versions such as 5.0.0-beta.1 that consumers must opt into explicitly; they sort below 5.0.0, promise no stability, may change between betas, and let pilot apps prove the migration guide first.

solid answer

~40 s

Semantic versioning lets you append a pre-release label, such as `5.0.0-beta.1`. The spec says a pre-release has lower precedence than its normal version and may not satisfy the compatibility the normal version will promise - so consumers must opt in deliberately, usually by pinning the exact pre-release, and must expect changes between betas. For a UI library the plan is: cut a beta once the breaking changes are in, have two or three pilot product surfaces migrate using the draft migration notes, fix what they hit, move to a release candidate once the API is frozen, and ship `5.0.0` when pilots run clean. The one thing never to do is make a pre-release the version consumers get by default.

go deeper

for a junior

Recall that a hyphenated label marks a pre-release, that it sorts below the final version, and that you only install one deliberately.

for a middle

Explain the precedence rules and the missing compatibility promise, then walk through a beta-to-rc-to-final plan with pilot consumers opting in.

for a senior

Show how you choose pilots, keep the stable line maintained, track who runs pre-releases in production, and use pilot feedback to correct the migration guide.

for a principal

Weigh how long a major should bake in pre-release against the cost of running two lines, and when a small major can skip the pre-release stage.

## What a pre-release is Under **semantic versioning**, a **pre-release** is a version with a hyphen and dot-separated identifiers after the patch number: `5.0.0-alpha.1`, `5.0.0-beta.2`, `5.0.0-rc.1`. The specification gives it two properties that matter to a component library: - **Lower precedence.** A pre-release sorts *below* its associated normal version, so `5.0.0-rc.1` comes before `5.0.0`. - **No compatibility promise.** A pre-release indicates the version is unstable and might not satisfy the compatibility requirements its normal version will denote. Build metadata, written after a plus sign, is a different thing: it is ignored for precedence and does not mark a version as unstable. ## How pre-releases order Precedence compares dot-separated identifiers left to right. Purely numeric identifiers compare **numerically**; identifiers with letters compare **lexically in ASCII order**; a numeric identifier sorts below an alphanumeric one; and a longer set wins if all earlier identifiers are equal. So: | Version | Position | |---|---| | `5.0.0-alpha.1` | earliest | | `5.0.0-beta.2` | after alpha, since beta sorts after alpha | | `5.0.0-beta.11` | after beta.2, since 11 compares numerically | | `5.0.0-rc.1` | after every beta | | `5.0.0` | the final release, above all its pre-releases | The dot matters: `beta11` and `beta2` without a dot compare as strings, and `beta11` sorts first because the character 1 precedes 2. ## A trial plan for a breaking UI major For a food-delivery app's shared library moving from 4.x to 5.0.0: 1. **Land the breaking changes** on the major line, each with a change entry saying what broke and how to migrate. 2. **Publish a beta** and keep the stable 4.x line as the version everyone installs by default. 3. **Recruit pilots** - surfaces that exercise the breaking changes heavily and whose teams can absorb churn, such as the restaurant menu and order-tracking screens rather than payment. 4. **Pilots opt in explicitly**, usually by pinning the exact pre-release, migrate using the draft notes, and report what the notes missed. 5. **Iterate betas**; breaking changes between betas are allowed, but list them so pilots can follow. 6. **Cut a release candidate** once the API is frozen - by common convention an rc means no further intended API changes, only fixes. 7. **Ship 5.0.0** when pilots run cleanly, with the migration guide their experience corrected. ## What the labels usually mean The spec gives the labels no meaning beyond ordering; teams agree on conventions: | Label | Common meaning | |---|---| | alpha | incomplete; API still moving | | beta | feature-complete for the major; API may still change | | rc | API frozen; only fixes before final | ## Communicating the trial A pre-release only helps if the right people know about it and can act on it: - **Announce what is breaking**, with the draft migration notes, when the first beta ships - not at the final release. - **List changes between pre-releases** so pilots can follow each step rather than rediscovering the diff. - **Give a feedback channel and a deadline** so pilot findings arrive before the API freezes at the release candidate. - **State the support plan for the old major**, so teams that cannot migrate yet know how long fixes will keep coming. ## Pitfalls - **Pre-releases in production by accident.** A team that pins a beta and forgets keeps an unstable version live; track who is on which pre-release. - **A pre-release as the default channel.** Everyone who installs without a version would receive unstable software. - **API changes after rc.** They invalidate the pilots' confidence; if one is unavoidable, cut another rc. - **Confusing build metadata with pre-release.** A plus-sign suffix does not warn anyone about instability. - **Starving the stable line.** While the major bakes, consumers on 4.x still need fixes, so plan for the parallel maintenance. Used this way, pre-releases turn a breaking major from a surprise into a rehearsed migration, and the migration guide consumers finally read has already been tested by real apps.

  • Can a breaking change land between 5.0.0-beta.1 and 5.0.0-beta.2?
    Yes. The specification says a pre-release might not satisfy the compatibility requirements its normal version implies, so nothing obliges betas to stay compatible with each other. Pilots accept that, but the library should still list every change between betas. Freezing the API is what a release-candidate label conventionally signals.
  • Why label betas beta.2 and beta.11 rather than beta2 and beta11?
    Semantic versioning compares dot-separated identifiers: purely numeric ones numerically, anything containing letters lexically in ASCII order. With the dot, 11 is a number and sorts after 2. Without it, beta11 and beta2 are compared as strings, and beta11 sorts first because the character 1 precedes 2.
  • Which consuming teams make good pilots for a UI library beta?
    Teams whose screens exercise the breaking changes most heavily and who can absorb churn - in a food-delivery app, perhaps the restaurant menu and order-tracking screens rather than payment. Their migration effort calibrates the guide, and their bugs surface before every other team upgrades.

saying these in an interview costs you the question

  • A pre-release sorts after the final version because it was published later.
  • Betas of the same major must stay compatible with one another.
  • Making the beta the default install is the fastest way to get feedback.
  • A plus-sign build suffix marks a version as a pre-release.
  • A release candidate may still take breaking API changes as a matter of course.