HeadVer Spec
A SemVer-compatible versioning system with {head}.{yearweek}.{build} format, where only the head number is manually set.
What is HeadVer Spec?
HeadVer is a versioning specification that provides a structured, automated alternative to traditional Semantic Versioning (SemVer). It uses a {head}.{yearweek}.{build} format where only the head number is manually set, while the year-week and build numbers are automatically generated, simplifying release management and ensuring incremental, traceable versions.
Development teams, DevOps engineers, and release managers who want to automate versioning, reduce manual errors, and have clear, time-based version identifiers.
It eliminates common versioning debates and errors by automating most of the version number, provides built-in age tracking via ISO-8601 week dates, and guarantees unique releases with incremental build numbers.
Overview
SemVer compatible version specification that has {head}.{yearweek}.{build} system.
Use Cases
Best For
- Teams wanting to automate version numbering in CI/CD pipelines
- Projects seeking a time-based versioning system for traceability
- Reducing manual version update commits in release workflows
- Ensuring unique version numbers across all releases
- Simplifying SemVer adoption with less decision overhead
- Tracking version age without external tools
Not Ideal For
- Projects requiring detailed semantic versioning for dependency management (e.g., libraries where patch/minor/major breaks are critical)
- Teams with daily or multiple releases per week, where weekly-based {yearweek} provides insufficient granularity
- Environments without a dedicated build server to auto-increment the {build} number
Pros & Cons
Pros
Only the head number requires manual setting, reducing human error and eliminating 'forgot to update version' commits, as {yearweek} and {build} are auto-generated from the README examples.
The {yearweek} part uses ISO-8601 week dates, allowing developers to instantly see how old a version is, which aids in support and issue tracking, as highlighted in the benefits section.
Auto-incremental build numbers ensure every release has a distinct version, preventing duplicates even if manual updates are missed, as emphasized in the rules.
HeadVer is designed to work with existing x.y.z systems, making it easy to adopt without breaking current workflows, as stated in the introduction and benefits.
Cons
By collapsing versioning to one manual number, HeadVer loses the patch/minor/major distinctions that SemVer uses to signal breaking changes or feature additions, which might confuse dependency management.
Implementing {yearweek} requires accurate ISO-8601 week date calculations, which have edge cases (e.g., year boundaries) shown in the validation table, making it error-prone for custom implementations.
The system assumes a build server is available to stamp incremental build numbers, as recommended in the rules, which may not be feasible for all projects or could tie versioning to specific infrastructure.
Frequently Asked Questions
Related Projects
React RFCsRFCs for changes to React
Vue RFCsRFCs for substantial changes / feature additions to Vue core
OTEPsSpecifications for OpenTelemetry
Compose SpecificationThe Compose specification
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.