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

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

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-]+)*))?$

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