SuperAPI AI Directory

version-management

General & other

View repository

Updated 10-16 02:31

About this skill

Version Management

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

  1. Single version source—an artifact recognizes onlyone placefor the version number (SKILL.md frontmatter / VERSION / package.json field / language convention…); everything else is derived. If two independently maintained places are found → unify first, then bump。
  2. 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。
  3. 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.
  4. Do not overstep—only manage version numbers; branches/commits/PRs go through git-workflow, dependency versions and vulnerabilities go through dependency-scan。
  5. 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's 1!, 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)、npm deprecate、Go retract, 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.3 may point to different digests; in production, pin by digest , with tags as human-readable aliases only.latest is not a version number.

Single version source and automation

  1. Locate the single source(read first, then modify):package.json / pyproject.toml / Cargo.toml / *.csproj / VERSION / SKILL.md frontmatter / language convention.
  2. Modify only this one place, everything else is derived (README version table, manifest index, CHANGELOG headings).
  3. If you find the same number written in multiple places → mark it as "should be derived" and normalize: this is the drift'sonlyroot cause.
  4. 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 a git-workflow boundary and requires user confirmation.
  • Without VCS: maintain RELEASES.md(or releases.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/Sunset header · 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。