Calendar Versioning (CalVer): Versioning That Ages Well

Versioning gets better with time. That’s the premise of Calendar Versioning (CalVer), a pragmatic alternative to semantic versioning that aligns software releases with the calendar instead of arbitrary numeric increments. In projects where time matters more than the nature of the change, CalVer brings clarity, predictability, and context.

What is CalVer?¶

CalVer is a date-based versioning convention where the version string encodes the release date, typically using combinations of year (YYYY), month (MM), day (DD), and optional modifiers (alpha, rc, dev, etc). This makes version numbers more transparent and easier to interpret at a glance.

Unlike Semantic Versioning, which emphasizes change severity and compatibility, CalVer emphasizes when, making it ideal for:

• Projects with frequent, scheduled releases
• Systems with long-term support cycles
• Projects driven by external timelines (e.g., timezones, security patches)

Common CalVer Schemes¶

Projects using CalVer often follow patterns like:

Modifiers like -alpha, -beta, and -rc1 may follow these schemes for pre-release tags.

Why Use CalVer?¶

CalVer is especially useful when:

• Scope is too large for isolated semantic bumps (e.g., operating systems)
• Time matters more than change magnitude (e.g., security patches)
• Support cycles are tied to release dates (e.g., LTS versions)
• Frequent releases occur based on policy or external triggers

If versioning is meant to communicate relevance, freshness, and lifecycle, CalVer is often the better tool.

Case Studies¶

Ubuntu¶

Uses YY.MM (e.g., 24.04) to align with biannual releases. The version doubles as a support indicator, LTS versions (like 20.04) receive 5 years of updates.

Twisted¶

A Python framework with YY.MM.PATCH. Major compatibility breaks require a one-year notice and two releases.

IANA Timezone Database¶

Uses YYYYa, YYYYb, etc., reflecting unpredictable political timezone changes.

Should You Use CalVer?¶

Ask yourself:

• Does your project grow organically or change frequently?
• Are updates driven by external schedules (security, policy)?
• Do users need to easily match versions to dates or support windows?

If yes, CalVer likely suits your needs better than SemVer.

Final Thoughts¶

CalVer is not just a versioning format, it's a communication tool. It aligns releases with real-world time, offering immediate context for users, maintainers, and stakeholders. When predictability, release cadence, or support windows are more important than strict compatibility semantics, CalVer excels.

By embedding time directly into your versioning, you simplify lifecycle management, streamline upgrade paths, and build trust through transparency. It's pragmatic, readable, and increasingly adopted across mature, high-impact projects.