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

docs: add versioning.md — PEP 440 vs SemVer 2.0, build channels, nightly pivot

Documents, with verified evidence (not assertion): - Why pyproject.toml (PEP 440 canonical, e.g. 0.2.0rc16) and muse release tags (SemVer 2.0 canonical, e.g. v0.2.0-rc.16) are two genuinely incompatible canonical strings for the same release, each required by a different real tool (pip/build/twine vs muse/core/semver.py). - Side-by-side comparison table, including a real gotcha: SemVer has no reserved stage names, so alphabetical sort of alpha/beta/nightly/rc gives the wrong maturity order (nightly sorts between beta and rc, when it should sort first) — PEP 440's reserved dev/a/b/rc segments don't have this problem. - The four build channels (nightly, alpha, beta, rc) with precise definitions and both canonical formats for each. - The pivot to nightly: what's been called "rc" in recent releases was actually continuous feature delivery shared with stakeholders, which is nightly by definition (rc implies feature-frozen, bug-fixes-only). - A decision table for which format to use in which context, and a translation table between the two formats for the same release. - Documents a real gap this work surfaced in muse's own tooling: semver_channel() had no rc branch (fixed separately in the muse repo).

Also updates deploy.md to link to the new doc and reinforce PEP 440 canonical form at the version-bump step.

sha256:43b5ad9422686d7119910384e280e85fcf78250346c551eea3b6977d2052880c sha
sha256:b344b9b06bee0f5fffc5439f311efc82cc11fd0efecd04cc7602ffe30a7fa3cc parent
+22 ~8 symbols
2 changed · 1006 in snapshot files
sha256:2284bb3268474c48899457c7bee13afbc8b08918a2a2cbc152a4383c32c55f96 snapshot
+22
symbols added
~8
symbols modified
2
files changed
1006
files in snapshot
0
dead code introduced
Semantic Changes 30 symbols
~ docs/versioning.md .md 22 symbols added
+ 0, and Build Channels section Versioning — PEP 440, SemVer 2.0, and Build Channels L1–220
+ Decision table — which format, when section Decision table — which format, when L165–175
+ table section table L167–174
+ Known gap this doc surfaced section Known gap this doc surfaced L191–201
+ 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
+ code[python] variable variable code[python] L69–73
+ table section table L54–63
+ Related section Related L217–220
+ Terminology — you don't need to ditch "release candidate" section Terminology — you don't need to ditch "release candidate" L201–217
+ 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–165
+ Translating between the two for the same release section Translating between the two for the same release L175–191
+ table section table L183–190
+ Why two formats — the tooling reality section Why two formats — the tooling reality L11–52
+ code[python]@L18 variable variable code[python]@L18 L18–28
+ code[python]@L39 variable variable code[python]@L39 L39–46
~ docs/deploy.md .md 8 symbols modified
~ code[bash]@L40
~ code[bash]@L47
~ code[bash]@L63
~ code[bash]@L104
~ code[bash]@L88
~ Deploy Runbook
~ Standard release flow
~ code[bash]
Files Changed
+1 ~1
1006 in snapshot
+ docs/versioning.md .md
~ docs/deploy.md .md
← Older Oldest on docs/versioning-guide
All commits
Newer → Latest on docs/versioning-guide

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:43b5ad9422686d7119910384e280e85fcf78250346c551eea3b6977d2052880c --body "your comment"