microsoft / microsoft/microsoft-ui-reactor
[Feature] Realign minver `-p experimental.0` to `preview.0` before the first stable tag
- Dominant language
- C#
- Stars
- 646
- Forks
- 54
- Avg merge
- 1d 3h
- Merged PRs (30d)
- 84
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](https://github.com/adamralph/minver#how-it-works), `-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.+
```
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`:
```diff
-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** / **nightly** — `experimental` 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* #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
- #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 (819a2067); 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
- [x] I have searched existing issues and specs for prior discussion of this idea.
Contributor guide
Research direction
Read the two MinVer invocations in .github/workflows/release.yml and build/pipelines/templates/reactor-build-steps.yml, then review docs/specs/022-packaging-and-distribution.md §8 and docs/specs/057-release-channels.md §3. Update both call sites together and simplify the related explanations in release.yml, reactor-build-steps.yml, and spec 022; done means the build paths use preview.0 consistently and the documentation matches the channel taxonomy.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- github-actions
- Domain
- build-system, ci-cd, documentation, release
- Issue type
- Feature
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 72/100