Role
Cross-language, cross-VCS version management:assign numbers → record changes → mark releases → check consistency. It can be fully executed without git (degrading to file conventions).
There is only one core judgment:a version number is a compatibility promise to users, not a build-count counter.
Trigger Scenarios
- Which version number should be released? Does this change count as MAJOR / MINOR / PATCH?
- Does this change count as "breaking"? Where is the boundary?
- To deprecate a feature, how should it be scheduled so it doesn't feel like a surprise attack?
- Write or update CHANGELOG, release notes
- Mark a release (with git → tag; without git → RELEASES list)
- Audit whether version numbers in multiple places are consistent, and whether multi-artifact/multi-package releases are aligned
Hard Constraints
- Single version source—an artifact recognizes onlyone placefor the version number (
SKILL.mdfrontmatter /VERSION/package.jsonfield / language convention…); everything else is derived. If two independently maintained places are found → unify first, then bump。 - Published is immutable—once a version number is published, its contents are frozen; corrections go througha new version number. For retraction, use the ecosystem's yank/deprecate mechanism,never republish the same number。
- Do not guess compatibility—breaking determinations are based onexternal contracts, and must considerimplicit interfaces(see below). When it cannot be determined, ask the user; do not default.
- Do not overstep—only manage version numbers; branches/commits/PRs go through
git-workflow, dependency versions and vulnerabilities go throughdependency-scan。 - Decisions are traceable—the basis for version decisions (what contract was broken, why this digit) must be findable, not just in your head.
Assigning Numbers: SemVer Decision Table
| Nature of Change | Version Digit | Example |
|---|---|---|
| Breaks external contract (incompatible) | MAJOR | Delete/rename public API, change required parameters, change data format, change error semantics |
| Add capability in a backward-compatible way | MINOR | Add optional API/field/subcommand |
| Mark deprecation(feature still present) | MINOR | Specification hard requirement: deprecation must be released as MINOR; removal can only be a MAJOR change |
| Fix in a backward-compatible way | PATCH | Fix bug, change copy, internal refactor |
| Metadata only (docs/comments/tests) | PATCH | No behavior change |
0.y.z(pre-stable period) |
Semantics relaxed | y increments may include breaking changes,z increments are fixes |
Decision order: whether it breaks the external contract → whether it adds capability → whether it deprecates → otherwise PATCH.When in doubt, always take the higher digit(the specification's attitude: breaking changes should make people pay the thinking cost of "switching major versions").
Details: when MAJOR is raised, minor/patch reset to zero; when MINOR is raised, patch resets to zero; no leading zeros;0.y.z during this period anything "may" change, butshould be communicated。
How to judge compatibility (the harder part than "is there documentation")
Three layers, from outer to inner:
| Layer | Content | Does breaking it count as MAJOR |
|---|---|---|
| Documented contract | Behavior explicitly promised by README/API reference/type signatures | Yes |
| Observable behavior (implicit interface) | Timing, error codes, log formats, sort stability, performance magnitude, boundary values | Yes(users already depend on it) |
| Pure implementation details | Private functions, internal data structures, uncommitted tiny performance differences | No (but it may also become the layer above) |
Hyrum's Law: when there are enough users,all observable behavior will be depended on by someone. So "the rules say this is not an API" is not enough to exempt a break—judge bythe behavior actually depended on.
Empirical warning: do not trust version numbers. A study of Maven Central found that aboutone thirdof releases contain at least one breaking change; follow-up replication studies give a SemVer violation rate of 22.8% . The implication is bidirectional:
- As apublisher: your MINOR/PATCH may also be treated as breaking by users, so "deprecation + warnings + migration path" saves more people than the version number itself.
- As auser: do not upgrade based only on the version position, especially for 0.x and low-maturity dependencies.
Breaking change checklist (for self-checking): deleting/renaming public symbols · changing function signatures or argument requiredness · changing return types/structures/field names · changing error types, error codes, exception semantics · tightening input validation · changing default values · changing serialization formats · raising minimum runtime environment requirements (language/runtime/OS version) · removing configuration options or flags · changing CLI output format (if parsed by scripts) · changing sorting/pagination/deduplication behavior · significant performance regression or resource usage change · transitive upgrades of dependencies causing any of the above.
Automate it if you can detect it automatically: API diff, contract tests, compile/type checks, golden file comparison.If you cannot detect it, do not declare MINOR.
Deprecation policy (deprecate first, remove later)
Canonical chain:Deprecate → release MINOR → pass at least one MINOR → remove only in the next MAJOR. Breaking changes must never arrive suddenly.
Tiered windows (borrowing Kubernetes' mature practice):
| Stability level | Minimum survival after deprecation |
|---|---|
| Stable/GA | Within the current major versionnot removed; deprecation requires an announcement |
| Beta | About 3 minor versions or 9 months (whichever is longer) |
| Alpha | Can be removed at any time, without prior announcement |
The four-piece set of deprecation(none may be missing): documentation annotation · runtime warning · migration path · timeline (when it will be removed). See the text template you can directly apply at references/deprecation-templates.md。
For HTTP / API scenarios, use standard signals so callers canautomatediscovery:Deprecation response headers (RFC 9745) give the effective time + Sunset header (RFC 8594) giving the shutdown time + Link pointing to migration documentation. "Delete first, announce later" is forbidden.
Choice: SemVer or CalVer
- SemVer: has a clear external API and users depend on compatibility promises — libraries, frameworks, CLIs, SDKs.
- CalVer: broad or frequently changing scope (OSes, distributions), time-sensitive (certificates, timezone libraries), releases driven by external events (such as API services versioned by date). CalVer directly conveys "when it's from" and allows arithmetic tied to support cycles.
- Switching the ordering breaks: switching from CalVer to SemVer produces an inversion of
1.0 < 2014.04→ use epoch(PEP 440's1!, Debian/RPM epoch) to lift the new scheme as a whole above the old one. Use epoch only once in a lifetime; once used, don't go back. - Four-segment numbers are not recommended (CalVer explicitly says so); pre-release/build metadata only has standard semantics in SemVer.
Immutable releases
- Published = content frozen. Bytes under the same version number never change; re-built artifacts are marked with build metadata/digests, without changing the version number's semantics.
- Retraction methods by ecosystem(all are "marking" rather than "erasing history"): PyPI
yank(PEP 592)、npmdeprecate、Goretract, NuGet unlist; Maven Central basicallydoes not acceptretraction and re-release. So self-checking before release matters far more than retracting afterward. - Security incidents: mark in the CHANGELOG with
[YANKED]and state the reason — loud, parseable, searchable. - Artifacts immutable ≠ tags immutable: container image tags are mutable pointers; the same
:1.2.3may point to different digests; in production, pin by digest , with tags as human-readable aliases only.latestis not a version number.
Single version source and automation
- Locate the single source(read first, then modify):
package.json/pyproject.toml/Cargo.toml/*.csproj/VERSION/SKILL.mdfrontmatter / language convention. - Modify only this one place, everything else is derived (README version table, manifest index, CHANGELOG headings).
- If you find the same number written in multiple places → mark it as "should be derived" and normalize: this is the drift'sonlyroot cause.
- After changing,check back for consistency.。
Automate on "derivation", not on "adding new sources" (chooseone, don't stack):
| Driving method | Representative | Applicable |
|---|---|---|
| Standardized commits → automatic version determination | semantic-release、release-please(manifest)、changesets | Projects already using Conventional Commits |
| Derive version from SCM | setuptools_scm、hatch-vcs、git describe |
Commit history as the truth, no hand-written numbers |
| Explicit file + human-written | VERSION、frontmatter |
No VCS or needs human review |
Commonality: tools are only responsible forderiving and writing back to the single source; once a tool automatically rewrites the version number, any hand-written second place immediately becomes a conflict source. Auto-generated CHANGELOG still needs human review(it's for users to read, not a commit dump).
CHANGELOG (Keep a Changelog convention)
- File
CHANGELOG.md,newest at the top, one section per version:## [X.Y.Z] - YYYY-MM-DD(ISO date, to avoid ambiguity). - Fixed grouping:
Added / Changed / Deprecated / Removed / Fixed / Security(omit empty groups). - Foruserswrite "what changed", not the commit log;every version must have an entry, an inconsistent CHANGELOG is more dangerous than none.
## [Unreleased]accumulate first, and turn them into a version number at release.- Must be explicitly listed: deprecated items, removed items, and any breaking changes (this is the line readers need most).
- Mark broken versions with
## [0.0.5] - 2014-12-13 [YANKED]。 - Without VCS, the CHANGELOG is theonly timeline。
of changes.
- With VCS (git): tag the release commit with
vX.Y.Z(annotated tags can carry release notes).Only tag, do not rewrite history; moving an already-published tag is agit-workflowboundary and requires user confirmation. - Without VCS: maintain
RELEASES.md(orreleases.json) — each entry: version number · date · CHANGELOG anchor · artifact digest (e.g. sha256). - Order: write the version source and CHANGELOG first → then tag; if you tag wrong, only delete the tag, do not touch the artifacts.
Prereleases and build metadata
- Prerelease:
X.Y.Z-alpha.N/-beta.N/-rc.N. Within the same series the number increments;an official release drops the suffix, and do not retroactively change an already-published prerelease number. - Ordering:
1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-beta < 1.0.0-rc.1 < 1.0.0; numeric segments compare numerically, alphanumeric segments compare by ASCII, and numeric segments have lower priority. - Build metadata:
X.Y.Z+<build>——does not participate in precedence comparison, it is only an identifier. - Ecosystem translation: SemVer's
-/+is illegal in some ecosystems (e.g. Python public version positions), so it needs translation (using.devN/local segments); do not force it in.
Multi-artifact / multi-package alignment
Three strategies,choose one and write it into the repository(terminology taken from changesets):
| Strategy | Behavior | Applicable |
|---|---|---|
| independent | Each is versioned independently | The lifecycles of the packages are unrelated |
| fixed | The whole groupshares the same version number, and if anything changes the whole group is released (including packages with no changes) | Suites that must be upgraded in pairs |
| linked | The whole group shares a number, butonly bump the ones that changed | Same family but not strongly coupled |
Userangesfor cross-package references rather than exact numbers (unless intentionally pinned); explain the applicable scope of a batch release in the CHANGELOG.
Output format
## 版本决策
现状:当前 <X.Y.Z>(源:<文件:行>)· 变更:<摘要>
判定:<MAJOR/MINOR/PATCH> · 理由:<破坏哪条契约 / 新增什么 / 是否弃用>
## 落地
- 版本源:<文件:行> → <X'.Y'.Z'>
- CHANGELOG:<新增节 + 分组条目(含废弃/移除/破坏性显式列出)>
- 发布标记:git tag `vX'.Y'.Z'` 或 RELEASES 记录
- 一致性回查:<引用点清单 → 全部一致 / 待改 …>
- 破坏性自检:<清单比对结果 / 自动检测手段与结果>
Anti-patterns
- Maintaining the same version number independently in multiple places (inevitably drifts)
- Releasing only PATCH/MINOR for breaking changes, using the version number to conceal breaking changes
- Releasing MAJOR for documentation-only changes (noise); or not releasing MINOR for deprecations
- Removing without a deprecation window; announcing only after deletion
- Re-releasing/reusing/decrementing an already-published version number; changing the contents under the same number
- Treating a tag or image tag as the source of truth for the version number (tags are mutable)
- Writing the CHANGELOG as a list of commits, or writing it after the fact in a distorted way
- Without VCS, no release record is left (timeline lost)
- Going out of bounds to rewrite git history or move an already-published tag
Completion criteria
- The version source is located toa singleplace and has been updated, with reference points back-checked for consistency
- The bump level is justified (against the decision table, stating which category: breaking/added/deprecated)
- The breaking determination is justified or has detection means (not just "I think it's compatible")
- When deprecation is involved: the full set of four is complete (documentation · warnings · migration path · timeline) and the window complies
- CHANGELOG has a new version section + grouped entries (deprecated/removed/breaking explicitly listed)
- Release markers are placed according to environment (git tag or RELEASES record)
- VCS history untouched, published version numbers unchanged
Reference materials (progressive disclosure)
references/ecosystems.md——Comparison table of version formats/ordering/ranges/immutability across ecosystems (npm · Python · Go · Maven · NuGet/.NET · Android · Apple · OCI · K8s · Stripe)references/deprecation-templates.md——Deprecation announcement template set (documentation annotation · runtime warning ·Deprecation/Sunsetheader · CHANGELOG entry · migration guide skeleton · self-check checklist)references/research.md——Methodology sources, empirical data, industrial precedents, and source list
Methodology sources (summary)
Semantic Versioning 2.0.0 · Keep a Changelog 1.1.0 · Conventional Commits 1.0.0 · Calendar Versioning (CalVer) · PEP 440 · Go Module version numbering · Kubernetes Deprecation Policy · Hyrum's Law · RFC 9745 / RFC 8594. Full sources see references/research.md。