Rhythm Versioning
Rhythm versioning (RhyVer) helps teams maintain momentum and follow a release cadence. Using the format vMAJOR.YYQ#.WEEK.STORY, it combines semantic versioning principles with granular temporal context, creating a natural rhythm for software releases.
For example, v2.24Q4.45.32 indicates a major version 2 release from the year 2024, Q4, ISO week 45, with 32 backward compatible changes, enabling predictable release cycles and better alignment with business goals.
Summary
Given a version vMAJOR.YYQ#.WEEK.STORY, increment the:
- MAJOR version when you make API compatibility changes.
- YYQ# to match the current year and quarter.
- WEEK number to match the ISO week (1-53).
- STORY for backward compatible changes that do not change the API.
Rhythm Versioning Specification
vMAJOR.YYQ#.WEEK.STORY[-PRERELEASE][+BUILD]
Example: v2.24Q4.45.32-rc.2
│ │ │ └────── Stories
│ │ └───────── ISO week
│ └────────────── Year & quarter
└──────────────── Major version
Components
- 01. MAJOR
- Non-negative integer with a prefix “v”.
- Changes for incompatible API modifications.
- Example: v2 indicates a major version 2.
- 02. YYQ#
- YY: Two-digit year (23, 24, etc.).
- Q#: Quarter number (Q1-Q4).
- Provides fiscal/planning context.
- Example: 24Q2 = 2024, Quarter 2
- 03. WEEK
- ISO week number (1-53).
- Maintains global standard.
- Continuous through year.
- Example: Week 18 (Standard ISO week)
- 04. STORY
- Non-negative integer.
- Backward compatible changes within the week.
- Incremental updates and bug fixes.
- Example: 1
- 05. PRERELEASE (Optional)
- Optional preview releases.
- Format: -alpha.1, -beta.1, -rc.1
- Example: v2.2024.43.0-beta.1
- 06. BUILD (Optional)
- Optional build metadata.
- Format: +build.123
- Example: v2.2024.43.0+build.123
Why Use Rhythm Versioning?
A structured versioning approach that aligns development with business cycles, making release patterns and timing clear to stakeholders.
Release discipline
- Enforces a regular release cadence through week-based versioning.
- Makes it obvious when releases are falling behind schedule.
- Helps teams maintain momentum by making irregular release patterns visible.
Business alignment
- Quarter designations align directly with business planning cycles.
- Stakeholders can immediately understand release timing without technical context.
- Simplifies reporting by matching fiscal/planning periods.
Time at a glance
- Makes it immediately clear when a release occurred.
- Provides historical context without checking logs or release notes.
- Teams can quickly identify how recent any version is.
Reading Your Business Rhythm
Interpreting version numbers as indicators of development pace and business cycles, with markers for healthy and concerning patterns.
v2.24Q4.45.32
│ │ │ └──── Weekly wins
│ │ └─────── Calendar pulse
│ └────────── Business cycle
└────────────── Major changes
Release Sequence
Week 27 │ v2.24Q3.27.0 Release of milestone 01
│ v2.24Q3.27.1 Polishing
│ v2.24Q3.27.2 Qualitative feedback
│
Week 28 │ v2.24Q3.28.0 Design improvements
│ v2.24Q3.27.1 Release of milestone 02
Risk Indicators
High risk
└── No releases for more than 2 weeks
└── Hotfix ratio greater than 20%
Low risk
└── Release gap of 1 week
└── Story count drops by 25%
Using in Design
Design files typically evolve incrementally with each iteration, so the granular "STORY" component is not as relevant. The version can be kept at the "WEEK" level.
Use the Rhythm Versioning format as the commit messages when saving new versions to make the version history more meaningful and aligned with development.
Version history commit
v2.24Q4.45.x // Major.YYQ#.Week
v2.24Q4.46.x // Week changes
v3.24Q4.46.x // Major version changes
Using with npm
Convert RhyVer to semantic versioning for npm compatibility.
{
"name": "package-name",
"rhyver": "v2.24Q4.45.32", // Store full RhyVer
"version": "2.45.32" // Simplified from v2.24Q4.45.32
}
RhyVer │ npm
v2.24Q4.45.32 │ 2.45.32 // Major.Week.Story
v2.24Q4.45.33 │ 2.45.33 // Story changes
v3.24Q4.46.0 │ 3.46.0 // Major version changes
Validation
Here's a simple regex pattern for validating rhythm version strings:
^v(0|[1-9]\d*)\.(2\d)Q([1-4])\.((?:[1-9]|[1-4]\d|5[0-3]))\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$
Examples
RhyVer adapts to real-world use cases. Below are a few examples of basic releases, pre-releases, and metadata.
RhyVer Version | Description |
---|---|
v1.24Q1.01.01 |
First major release, week 1, story 1. |
v1.24Q1.05.03-alpha |
Week 5, story 3, alpha pre-release. |
v2.24Q2.10.12 |
Week 10, story 12. |
v2.24Q2.15.20+build456 |
Week 15, story 20, tagged with build 456. |
v3.25Q3.28.13-beta.4 |
Week 28, story 13, fourth beta iteration. |
v4.26Q1.05.05 |
Week 5, story 5 |
v4.26Q3.20.07-beta |
Week 20, story 7, in beta. |
v5.25Q4.45.03+hotfix102 |
Week 45, story 3, tagged with hotfix 102. |
v7.27Q2.18.25+debug001 |
Week 18, story 25, debug build 001. |
v10.27Q4.47.25+prod1234 |
Week 47, story 25, production build 1234. |
v2.24Q4.50.32-alpha.2+ci789 |
Week 50, story 32, second alpha release, CI build 789. |
v3.25Q2.30.15-rc.1 |
Week 30, story 15, first release candidate. |
v4.26Q1.12.08-rc.3+exp1024 |
Week 12, story 8, third release candidate, experimental build. |
v0.24Q1.01.01 |
Initial version (v0), week 1, story 1. |
v1.25Q3.34.05-pre.0 |
Week 34, story 5, pre-release version 0. |
FAQs
How do I handle hotfixes vs regular stories?
Hotfixes and regular stories use the STORY number but can be distinguished by the release process. Use pre-release tags for hotfix candidates needing testing before deployment.
Regular story: v2.24Q2.16.0 → v2.24Q2.16.1 // Normal iteration
Hotfix from production: v2.24Q2.16.0 → v2.24Q2.16.1-hotfix.1 → v2.24Q2.16.1 // Emergency fix
What quarter applies to a release spanning multiple quarters?
Always use the quarter of the release, not when development started, to clarify when the software was released.
v2.24Q1.13.2 // Last release in Q1
v2.24Q2.14.0 // First release in Q2, even if dev started in Q1
How do I handle ISO week vs Quarter misalignment?
Use the quarter designation that best fits your reporting, regardless of ISO week boundaries. The Q# is for business context, while the ISO week number provides timing.
v2.24Q1.13.0 // Even if week 13 slightly overlaps Q2
v2.24Q2.14.0 // Starting Q2 designation with week 14
About
Rhythm versioning specification was originally authored by Abhimanyu Rana. To provide feedback or suggest improvements, please open a GitHub issue.
- Abhimanyu Rana
- Designer. Engineer.
- planetabhi.com