REF-067: Semantic Versioning 2.0.0
REF-067: Semantic Versioning 2.0.0
Citation
Preston-Werner, T. (2013). Semantic Versioning Specification (SemVer) 2.0.0. Semantic Versioning. https://semver.org/
Document Profile
| Attribute | Value |
|---|---|
| Year | 2013 |
| Type | Versioning specification |
| Status | Stable, widely adopted |
| GRADE / Quality | A - normative specification with broad ecosystem adoption |
| AIWG Relevance | High - Defines exact version precedence and immutability language for resource selectors |
Executive Summary
Semantic Versioning defines a public version contract using `MAJOR.MINOR.PATCH`, optional prerelease identifiers, and optional build metadata. Its two resource distribution lessons are directly applicable to AIWG:
1. Released version contents must be immutable; fixes require a new version. 2. Version precedence and prerelease ordering need one shared parser contract.
AIWG currently uses CalVer for project releases, but the web-resource selector contract still needs SemVer literacy for future range support and for operator expectations inherited from npm-like ecosystems.
AIWG Implementation Mapping
| SemVer Concept | AIWG Resource Implication |
|---|---|
| Immutable released version | A signed resource release must never be overwritten in place |
| Prerelease precedence | Candidate/canary channels must resolve to explicit immutable releases |
| Build metadata ignored in precedence | Build provenance belongs in manifests and lockfiles, not selector ordering |
| Public API requirement | Resource schema compatibility is part of AIWG's public CLI/resource contract |
Design Implications
- `--aiwg-version` range support should be implemented with a standards-backed
comparator, not an ad hoc string sort.
- Channel names are not versions. They are mutable pointers that must resolve
to an immutable version plus manifest digest before resource bytes are read.
- Lockfiles should persist the resolved immutable version, not only the
human-facing selector.
Cross-References
- REF-068: npm dist-tags and lockfiles apply SemVer expectations in a package
registry workflow.
- REF-072: TUF also uses version counters and rollback checks, but for metadata
freshness rather than API compatibility.
- `docs/install/web-backed-resources.md`: public AIWG web-resource selector
contract.