mirror of
https://github.com/magnus919/agent-skills.git
synced 2026-09-18 15:06: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>
62 lines
3.4 KiB
Markdown
62 lines
3.4 KiB
Markdown
# 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 CHANGE` forces a MAJOR at 1.0.0+, or a MINOR bump in 0.x, even if the rest are fixes. Automate with the `version_bump.py` script.
|
|
|
|
## Prerelease and Build Metadata Rules
|
|
|
|
- Prerelease identifiers: dot-separated alphanumerics + hyphens; numeric identifiers have no leading zeros (`rc.1`, not `rc.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
|