mirror of
https://github.com/magnus919/agent-skills.git
synced 2026-09-15 05:26:28 +03:00
github-actions[bot]GitHubgithub-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>Magnus Hedemark* chore(main): release 0.6.0 * fix(release-engineering): align validators with release tooling --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Magnus Hedemark <magnus919@pm.me>
3.4 KiB
3.4 KiB
Versioning Decision Table
Choose a versioning scheme, then encode the rules in your release tooling. Canonical definitions: SemVer 2.0.0, CalVer, and Conventional Commits.
Scheme Selection
| Question | If yes → |
|---|---|
| Do you have a public API or installable library where consumers depend on compatibility guarantees? | SemVer — each version carries semantic meaning |
| Is the product time-bound (releases must be date-identifiable) or driven by external events (regulatory, compliance)? | CalVer — date-based |
| Do multiple components ship on the same train with a shared promise (product suite, mobile app)? | Fixed / one-version — a single version for the product |
| Do components evolve independently and integrate via registries? | Independent versioning — per-component SemVer |
| Scheme | Format | Best for | Example |
|---|---|---|---|
| SemVer | MAJOR.MINOR.PATCH[-prerelease][+build] | Libraries, APIs, anything with consumers | 2.4.0, 2.4.0-rc.1 |
| CalVer | Date segments + optional modifier | Products with time-based releases | Ubuntu 24.04, pip 24.3 |
| Fixed / one-version | One version across all components | Release trains, product suites, mobile apps | 2026.08.1 |
| Independent | Per-component versions | Microservices, monorepo packages | api 3.2.1, web 1.9.0 |
SemVer Rules
| Component | Rule |
|---|---|
| MAJOR | Incompatible API change |
| MINOR | Backward-compatible new functionality |
| PATCH | Backward-compatible bug fix |
| 0.y.z | Initial development: anything may change; consumers should pin |
| Prerelease | -alpha.1, -beta.2, -rc.1 — lower precedence than the final release |
| Build metadata | +build.123, +exp.sha.5114f85 — ignored in precedence, useful for provenance |
Bump Rules from Conventional Commits
| Commit type | Bump | Example |
|---|---|---|
BREAKING CHANGE: footer, or feat! / fix! |
MAJOR | feat!: drop v1 API |
feat |
MINOR | feat(auth): add refresh tokens |
fix |
PATCH | fix(api): retry on 429 |
perf, refactor, docs, test, chore, ci, build, style |
PATCH in this skill | docs: update readme |
For 0.y.z, this skill's Release Please-compatible policy maps both
feat and breaking changes to MINOR (0.5.0 -> 0.6.0), while fixes and
other changes remain PATCH. At 1.0.0 and later, normal SemVer priority
applies.
Gotcha — the bump is decided by the highest-priority type in the release range: one
BREAKING CHANGEforces a MAJOR at 1.0.0+, or a MINOR bump in 0.x, even if the rest are fixes. Automate with theversion_bump.pyscript.
Prerelease and Build Metadata Rules
- Prerelease identifiers: dot-separated alphanumerics + hyphens; numeric identifiers have no leading zeros (
rc.1, notrc.01). - Prerelease precedence:
1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-beta < 1.0.0-rc.1 < 1.0.0. - Build metadata (
+...) does not affect precedence:1.0.0+001 == 1.0.0+002. - Promotion pattern: build once, record the digest, tag with SemVer, promote the same immutable artifact through environments — never rebuild for promotion.
Sources and Further Reading
- Semantic Versioning 2.0.0: https://semver.org/
- Conventional Commits 1.0.0: https://www.conventionalcommits.org/en/v1.0.0/
- CalVer: https://calver.org/
- Keep a Changelog: https://keepachangelog.com/en/1.1.0/
- Changesets (independent versioning in monorepos): https://github.com/changesets/changesets