docs: add ADR 0012 — pinned prerelease versioning for beta lines

[pomfrida]

Closes #5198

Summary

Records the versioning decision implemented in #5180 (eds-tokens) and #5190 (eds-core-react-next): both beta lines use release-please's versioning: "prerelease" + prerelease: true so the base stays pinned at 3.0.0-beta.N and every commit type only bumps the counter. Captures the non-obvious parts that live only in PR descriptions today:

• prerelease-type: beta alone does not pin the base — without prerelease: true, a fix on 3.0.0-beta.0 releases stable 3.0.0 (the exact drift from fix: pin EDS 2.0 beta releases to a fixed 3.0.0-beta.N series #5141)
• why eds-tokens uses release-type: simple (version.txt) — pnpm publish rewrites workspace:^ from package.json, which must stay on the stable version
• why the old "no ! in beta commits" rule is inverted
• rejected alternatives: custom version automation in the publish workflow (fix: pin EDS 2.0 beta releases to a fixed 3.0.0-beta.N series #5141's original prescription, based on an outdated premise) and a separate beta component

Notes

• Status is Proposed pending team review; the configuration is merged and validated in production (eds-tokens 3.0.0-beta.0 → 3.0.0-beta.1 on 2026-07-20).
• References ADR-0011 (docs: add ADR 0011 — adopt the Tokens Studio platform token pipeline #5195); merge order between the two doesn't matter — the links are by number.
• Numbered 0012: 0009 is taken by docs: add ADR for temporary next subpaths during eds-tokens beta #5194, 0010 is reserved for the CSS specifier layout decision, 0011 by docs: add ADR 0011 — adopt the Tokens Studio platform token pipeline #5195.

🤖 Generated with Claude Code

[pomfrida]

@claude review

[claude]

Claude finished @pomfrida's task in 1m 4s —— View job

---

Review: ADR 0012 — pinned prerelease versioning

Docs-only change. I verified every technical claim in the ADR against the repo, and the ADR is accurate. Summary and details below.

• Read the ADR
• Verify claims against referenced files/config
• Check ADR numbering & cross-links
• Post review

Verification ✅

The config the ADR describes matches .github/release-please-config.json exactly:

• packages/eds-core-react/src/components/next → release-type: simple, versioning: "prerelease", prerelease: true, prerelease-type: "beta" (lines 30–36) ✔
• packages/eds-tokens → same trio plus release-type: "simple" (lines 85–91) ✔ — matches the version.txt / workspace:^ rationale in the Decision section.
• The prerelease-type: beta alone does not pin claim, the inverted "no !" rule, and the 2.6.0-beta.0 → 2.7.0-beta.1 → 2.8.0-beta.1 drift are all corroborated by .github/release-please-config.md (lines 100–101, 125, 336). The ADR is consistent with the existing docs rather than contradicting them. ✔

All three referenced targets exist: .github/release-please-config.md, documentation/how-to/BETA_RELEASE_GUIDE.md, and issue/PR links are by number.

Findings

1. Broken relative link to ADR-0011 at merge time (lines 9, 62-ish, 93)

The ADR links [ADR-0011](./0011-adopt-tokens-studio-platform-pipeline.md) three times, but documentation/adr/ currently contains only 0008 → then jumps to this 0012; 0009, 0010, and 0011 don't exist on this branch. So these are dead relative links until #5195 merges, and the rendered filename must match #5195's actual filename exactly (0011-adopt-tokens-studio-platform-pipeline.md). Worth confirming the slug in #5195 matches before/at merge — a one-character difference in the slug leaves a permanently broken link even after both merge.

Not a blocker (the PR body flags the merge-order dependency), just make sure the two land consistently.

2. "Status: Proposed" vs. an already-implemented, production-validated config (lines 3, 83, 88–89)

The header says Proposed, but the Confirmation section states the config is merged and validated in production (eds-tokens 3.0.0-beta.0 → 3.0.0-beta.1 on 2026-07-20), and the config is live in release-please-config.json. That's a slight tension — a "Proposed" ADR documenting shipped, verified behaviour. This is intentional per the PR body (pending team review), so fine to keep, but consider flipping to Accepted once the team signs off, since the decision is already in effect.

Nits (non-blocking)

• Line 89: "The next /next merge to main must produce a release PR with eds-core-react-next: 3.0.0-beta.2" is a forward-looking assertion. Good as a falsifiable confirmation criterion, but it'll read as stale once satisfied — consider phrasing it as an expectation to check off rather than a standing "must".
• Line 83 parenthetical "exercised once for the docs-only 2.3.2" is a nice concrete detail; no change needed, just make sure that tag actually exists so the claim stays true.

Verdict

Clear, well-structured, and technically correct. The only actionable item is the relative link to a not-yet-existing ADR-0011 — verify the slug matches #5195 so the links resolve once both merge. Everything else is optional polish.
• docs/adr-0012-pinned-prerelease-versioning