gabriel / musehub public
docs docs/versioning-supercharge #1 / 1
AI Agent gabriel · 17 days ago · Jul 3, 2026 · Diff

docs: supercharge versioning.md — code-computed SemVer + zero-ambiguity cheat sheet

Now the canonical versioning reference, rewritten for an audience that already knows SemVer and cares about precision:

- New headline section: SemVer here is structurally computed, not a human promise. Documents the real pipeline (verified against muse/core/semver_classifier.py) — StructuredDelta -> invisible-rule filtering -> StabilityManifest -> ChangeClassifier -> SemVerAggregator -> SemVerClassification — with the exact bump matrix, the counter-intuitive "breaking-on-unstable = MINOR not MAJOR" rule and why it's correct, the exact pre-1.0 arithmetic from run_suggest(), a real .muse/stability.toml example, and a real `muse release suggest --json` output showing driver attribution (which commits/symbols caused the bump). - Ties this to muse code impact/gravity/deps: same symbol graph backs both the semver classifier and blast-radius queries — the version number and "who's affected" are two views into one fact, not two independently-maintained claims. - New cheat sheet up top: one-lookup table for which format/spec/example applies to which file, so the answer is never more than one glance away. Every internal anchor link verified against musehub's actual mistune-based heading-slug algorithm (ui_blob.py::_render_markdown), not assumed. - Updated the "known gap" section to "fixed" — the rc-channel bug this doc originally surfaced was already shipped in a prior commit. - Tightened all prior content (PEP 440 vs SemVer, channels, nightly pivot, numbering decision, terminology) for a reader who already knows what semver is — cut introductory explanation, kept verified specifics.

sha256:5e375cfafa44dfd6feaec471380eb146dcad3653b204db30cba03543a3ccc8bc sha
sha256:69ae50e537d929ac0661cd4da7f3e58719b13f80a1f799b072e874cd5ab6383e parent
+31 ~4 −19 symbols
1 changed · 1006 in snapshot files
sha256:21462fe1caee0b58790710da64da26870b9efe1196af52128973249d319b568a snapshot
+31
symbols added
~4
symbols modified
−19
symbols removed
1
file changed
1006
files in snapshot
0
dead code introduced
Semantic Changes 54 symbols
~ docs/versioning.md .md 31 symbols added, 19 symbols removed, 4 symbols modified
~ code[python]
~ table
~ code[python]@L18
~ code[python]@L39
− 0, and Build Channels section Versioning — PEP 440, SemVer 2.0, and Build Channels L1–248
− Decision table — which format, when section Decision table — which format, when L193–203
− table section table L195–202
− Known gap this doc surfaced section Known gap this doc surfaced L219–229
− 0 — side by side section PEP 440 vs SemVer 2.0 — side by side L52–85
− A real gotcha this comparison surfaces section A real gotcha this comparison surfaces L64–85
− table section table L54–63
− Related section Related L245–248
− Terminology — you don't need to ditch "release candidate" section Terminology — you don't need to ditch "release candidate" L229–245
− The four build channels section The four build channels L85–136
− Alpha — feature-incomplete section Alpha — feature-incomplete L102–111
− Beta — feature-complete, hardening section Beta — feature-complete, hardening L111–121
− Nightly — earliest, continuous section Nightly — earliest, continuous L91–102
− Release Candidate — frozen, final verification section Release Candidate — frozen, final verification L121–131
− Stable section Stable L131–136
− The pivot to nightly section The pivot to nightly L136–193
− Nightly numbering — decided: sequential auto-increment, reset to 1 section Nightly numbering — decided: sequential auto-increment, reset to 1 L158–193
− Translating between the two for the same release section Translating between the two for the same release L203–219
− Why two formats — the tooling reality section Why two formats — the tooling reality L11–52
+ Versioning section Versioning L1–385
+ Build channels section Build channels L274–331
+ Nightly numbering — decided: sequential auto-increment, reset to 1 section Nightly numbering — decided: sequential auto-increment, reset to 1 L301–331
+ The pivot to nightly section The pivot to nightly L289–301
+ table section table L281–288
+ Cheat sheet — zero ambiguity section Cheat sheet — zero ambiguity L10–35
+ table section table L12–18
+ Fixed gap: rc channel was silently classified as stable class section Fixed gap: rc channel was silently classified as stable L347–365
+ Related section Related L379–385
+ SemVer is structurally computed here, not conventionally promised section SemVer is structurally computed here, not conventionally promised L35–203
+ toml section Declaring stability — .muse/stability.toml L113–141
+ code[toml] variable variable code[toml] L119–135
+ 0 arithmetic — exact rule, not an approximation section Pre-1.0 arithmetic — exact rule, not an approximation L141–160
+ code[python] variable variable code[python] L145–154
+ Stability tiers section Stability tiers L81–89
+ table section table L83–88
+ The bump matrix section The bump matrix L89–113
+ table section table L91–97
+ The pipeline section The pipeline L45–72
+ code variable variable code L47–65
+ Visibility tiers section Visibility tiers L72–81
+ table section table L74–80
+ Why this is the reason SemVer matters here specifically section Why this is the reason SemVer matters here specifically L191–203
+ muse release suggest — the aggregation step section muse release suggest — the aggregation step L160–191
+ code[bash] variable variable code[bash] L166–184
+ Terminology — "release candidate" is not deprecated by "pre-release" section Terminology — "release candidate" is not deprecated by "pre-release" L365–379
+ Translating between the two formats for the same release section Translating between the two formats for the same release L331–347
+ Why two canonical formats, both load-bearing section Why two canonical formats, both load-bearing L203–274
+ A real gotcha — SemVer has no reserved stage names section A real gotcha — SemVer has no reserved stage names L255–274
+ Side by side section Side by side L243–255
+ table section table L245–254
Files Changed
~1
1006 in snapshot
~ docs/versioning.md .md
← Older Oldest on docs/versioning-supercharge
All commits
Newer → Latest on docs/versioning-supercharge

0 comments

No comments yet. Be the first to start the discussion.

To add a comment, use the Muse CLI: muse hub commit comment sha256:5e375cfafa44dfd6feaec471380eb146dcad3653b204db30cba03543a3ccc8bc --body "your comment"