Skip to content

0012-pinned-prerelease-versioning-for-beta-lines.md

Latest commit

 

History

History
97 lines (60 loc) · 6.96 KB

0012-pinned-prerelease-versioning-for-beta-lines.md

File metadata and controls

97 lines (60 loc) · 6.96 KB
Raw

Pin beta release lines to a fixed 3.0.0-beta.N series with release-please prerelease versioning

  • Status: Proposed
  • Date: 2026-07-20
  • Decision makers: Frida Erdal, EDS Core Team

Context

Two packages are in a beta phase ahead of a 3.0.0 major: eds-core-react-next (the /next EDS 2.0 components) and @equinor/eds-tokens (the Tokens Studio rework, ADR-0011).

The /next beta channel originally rolled its version base on every feat(next): 2.6.0-beta.0 → 2.7.0-beta.1 → 2.8.0-beta.1. That presented the betas as previews of stable 2.x minors, when EDS 2.0 actually graduates as 3.0.0 (#5141). The betas needed to be a fixed 3.0.0-beta.N series where only the counter climbs, regardless of commit type.

The same question arose for eds-tokens: during the Tokens Studio transition there is no stable release channel — consumers on latest stay on the last stable 2.3.1 — and every pipeline or code change should cut the next 3.0.0-beta.N.

An extra constraint applies to eds-tokens: four packages (eds-core-react, eds-utils, eds-lab-react, eds-data-grid-react) depend on it via workspace:^, and pnpm publish rewrites that to the version in eds-tokens' package.json. If package.json carried the beta version, stable releases of those packages would depend on beta tokens.

Decision Drivers

  • The version base must never move during beta — every commit type (fix, feat, feat!) bumps only the beta counter
  • Breaking changes must still surface as a "⚠ BREAKING CHANGES" changelog section for beta consumers
  • Stable releases of dependent packages must keep depending on stable tokens (workspace:^ rewrite)
  • Graduation to 3.0.0 must be a config flip, not re-plumbing
  • Prefer configuration release-please owns over custom version automation in workflows

Options Considered

Option 1: Custom version automation in the publish workflows

What #5141 originally prescribed, on the premise that release-please cannot pin a prerelease base: compute 3.0.0-beta.N in publish_core_react.yaml at publish time.

Pros:

  • Full control of the version string

Cons:

  • The premise is outdated — verified against release-please v17 source (src/versioning-strategies/prerelease.ts, bundled as 17.6.0 in release-please-action@v5), the prerelease strategy pins the base natively
  • Version would live in workflow logic, drifting from the manifest/version.txt release-please owns
  • Changelogs and GitHub releases would not match what is published

Option 2: Separate beta component/package per line

A dedicated release-please component (or package) per beta line with independent versioning, discarded at graduation.

Pros:

  • Beta and stable lines cannot interfere by construction

Cons:

  • Breaks tag and changelog continuity — history splits across components
  • More moving parts to dismantle at graduation

Option 3: release-please versioning: "prerelease" + prerelease: true (chosen)

Configure the existing components with release-please's prerelease versioning strategy, base seeded at 3.0.0-beta.N.

Pros:

  • release-please owns the version end to end (manifest, version.txt, changelog, tags)
  • Verified by running release-please's actual versioning code: fix, feat and feat! all produce beta.N+1 while minor and patch are 0
  • Graduation is flipping "prerelease": false (or a Release-As: 3.0.0 footer)

Cons:

  • Subtle: prerelease-type: beta alone does not pin — without prerelease: true the default strategy bumps the base and carries the suffix (the exact #5141 drift), and a fix on 3.0.0-beta.0 would release stable 3.0.0
  • The pin only holds while minor and patch are both 0

Decision

Use release-please's versioning: "prerelease" + prerelease: true + prerelease-type: "beta" on both beta lines, with the base seeded at 3.0.0-beta.N in the manifest. Every commit type bumps only the beta counter; feat!/fix! additionally emit a "⚠ BREAKING CHANGES" changelog section. The former "no ! in beta commits" rule is inverted: ! is now safe (the base cannot roll) and preferred, because it surfaces breaking changes to beta consumers.

For eds-tokens, the entry additionally uses release-type: simple, which tracks the version in version.txt instead of package.json. package.json stays at the last stable (2.3.1) so pnpm publish's workspace:^ rewrite keeps stable releases of dependent packages on stable tokens; the publish workflow applies the version.txt beta version at publish time. The existing component, tags, and CHANGELOG continue seamlessly — no separate -next component.

At graduation, flip "prerelease": false and switch the npm dist-tag from beta back to latest; the same configuration then emits stable 3.0.0.

Consequences

  • Good, because betas present honestly as 3.0.0-beta.N — previews of the actual next major, not of fictional 2.x minors
  • Good, because breaking changes in beta are encouraged to carry ! and get a changelog section, instead of being banned
  • Good, because both beta lines share one validated configuration pattern, and graduation is a config flip
  • Good, because stable releases of workspace:^ dependents keep resolving to stable tokens throughout the transition
  • Bad, because an urgent stable 2.x tokens patch during the transition is a manual publish from the eds-tokens@v2.3.1 tag (accepted — no stable tokens work is planned; exercised once for the docs-only 2.3.2)
  • Bad, because the eds-tokens version lives in two places with different meanings (version.txt = beta line, package.json = stable line) — a known sharp edge for anyone touching the publish flow
  • Bad, because the pin silently stops working if minor/patch ever leave 0 (e.g. a stray Release-As footer) — the base would start rolling again

Confirmation

Validated in production: the 2026-07-20 release moved eds-tokens 3.0.0-beta.0 → 3.0.0-beta.1 from a feat without rolling the base. The next /next merge to main must produce a release PR with eds-core-react-next: 3.0.0-beta.2. documentation/how-to/BETA_RELEASE_GUIDE.md and .github/release-please-config.md document the day-to-day rules.

Related