Skip to content

[Feature] Realign minver -p experimental.0 to preview.0 before the first stable tag #1127

Description

Problem

minver-cli is invoked with -p experimental.0 in two places:

  • .github/workflows/release.yml
  • build/pipelines/templates/reactor-build-steps.yml

Those identifiers have never appeared in a shipped version — all 13 tags are v0.1.0-preview.N — which is why #1126 documented the preview.N scheme rather than changing the flag.

The reason the flag is currently harmless is narrower than it looks, and it expires. Per MinVer's algorithm, -p supplies the default prerelease identifiers whenever MinVer must invent a label, which happens in two cases:

If the version is RTM (not pre-release): The patch number is incremented... Default pre-release identifiers are added. ... if the latest version tag is 1.0.0, the current version is 1.0.1-alpha.0.

  1. No reachable v* tag.
  2. The latest reachable tag is stable/RTM — patch bumped, identifiers added.

Case 2 is the problem. It is dormant today only because every tag so far is itself a prerelease, which MinVer carries forward with height. It is not dormant because tags exist, and fetch-depth: 0 does not prevent it.

Spec 022-packaging-and-distribution.md §8 already plans a stable tag (Tag push of v0.1.0 → 0.1.0 (stable, P3 only)). The commit after that tag would build as:

0.1.1-experimental.0.<height>+<sha7>

So the first stable release is the point at which the repo begins emitting the exact scheme #1126 documented as never having existed — in CI-built packages, on main and PR builds.

Proposed solution

Change both invocations to -p preview.0:

-minver -t v -p experimental.0 -m 0.1
+minver -t v -p preview.0 -m 0.1

Post-stable builds then become 0.1.1-preview.0.N, which matches the shipped scheme and the channel taxonomy in 057-release-channels.md §3 (stable / preview / nightlyexperimental is not a channel). The two call sites must change together to preserve the parity the pipeline template comment already calls out.

Then simplify the now-two-case explanations added by #1126 in release.yml, reactor-build-steps.yml, and spec 022 §8, which currently have to explain why a mismatched identifier is safe.

Timing: worth settling before the first stable tag. Afterwards, the fix is the same one-word edit, but any packages built in between carry an experimental label that was never intended, and 0.1.1-experimental.0.N sorts below 0.1.1-preview.0.N under SemVer — so a later correction re-orders the version stream rather than just renaming it.

Alternatives considered

  • Leave it. Zero effort, and correct until the first stable tag. Costs: the docs must carry a standing explanation of why the mismatch is safe, and the safety expires on a date nobody is tracking. This was the right call inside docs: document the preview.N version scheme, not experimental.N #1126 (a docs-only PR) but not indefinitely.
  • Drop -p entirely. Falls back to MinVer's default alpha.0 — swaps one non-existent label for another, and alpha isn't in the channel taxonomy either.
  • Handle it at the point of stabilization. Reasonable, but it becomes one more item on a release checklist that already has a two-person rule and a gated publish; a one-word change now removes it from that list.

Additional context

  • docs: document the preview.N version scheme, not experimental.N #1126 — documented the preview.N scheme; deliberately left both invocations byte-identical to keep it docs-only. Merged as 9ff765c.
  • The "only fires when untagged" belief was wrong and was corrected during review of that PR (819a206); this issue exists because the corrected behavior has a real consequence.
  • docs/specs/057-release-channels.md §3 — channel taxonomy.
  • docs/specs/022-packaging-and-distribution.md §8 — versioning, including the stable-tag row.

Confirmation

  • I have searched existing issues and specs for prior discussion of this idea.

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions