Rhythm Versioning

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:

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

View Raw

Why Use Rhythm Versioning?

A structured versioning approach that aligns development with business cycles, making release patterns and timing clear to stakeholders.

Release discipline
Business alignment
Time at a glance

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.

sign
Abhimanyu Rana
Designer. Engineer.
planetabhi.com