Why Our Versions Look Like Timestamps

The Versioning Problem

Most software uses SemVer: v1.2.3. Major.minor.patch. It encodes compatibility promises: major bumps break things, minor bumps add features, patches fix bugs. For libraries with public APIs, SemVer is the right choice — consumers need to know what’s safe to upgrade.

But iddio isn’t a library. It’s a self-contained binary that organizations deploy. Nobody imports iddio/pkg/proxy into their Go code. The “compatibility” dimension of SemVer doesn’t apply, and the version numbers become arbitrary — is v1.4.0 → v1.5.0 a bigger change than v1.3.0 → v1.4.0? There’s no way to know.

The Alternatives

We evaluated four versioning schemes:

SemVer (v1.2.3)

• Pros: Universal familiarity, compatibility semantics
• Cons: Compatibility semantics are meaningless for a deployed binary. Version number inflation (are we really on v14.0.0 after 14 breaking changes?). Arguments about whether a change is “minor” or “patch.”

Date-Based CalVer (v2026.02.20)

• Pros: Encodes release date, self-sorting
• Cons: Only one release per day. We sometimes ship multiple releases in a day during active development.

Sequential Build Numbers (build-1234)

• Pros: Monotonically increasing, simple
• Cons: No information content. “build-1234” tells you nothing about when it was built or what’s in it.

Git Hashes (a1b2c3d)

• Pros: Uniquely identifies the exact commit
• Cons: Not sortable, not human-readable, doesn’t indicate when the release was built.

Our Choice: Minute-Granularity CalVer

Iddio uses CalVer with minute granularity:

v2026.0220.2306
  │     │     │
  │     │     └── HHMM (23:06 UTC)
  │     └── MMDD (February 20)
  └── Year

This gives us:

• When it was built — embedded in the version string
• Multiple releases per day — minute granularity supports rapid iteration
• Self-sorting — versions sort chronologically
• No arbitrary decisions — no debates about major vs. minor
• Instant staleness detection — v2026.0115.0800 is obviously old when today is March

The Release Script

Versions are generated automatically by make release:

#!/bin/bash
VERSION="v$(date -u +%Y.%m%d.%H%M)"
# → v2026.0220.2306

echo "Releasing $VERSION"
git tag -a "$VERSION" -m "Release $VERSION"
git push origin "$VERSION"

No human decides the version number. It’s a function of the clock. The only decision is “should we release?” — and the answer to that is “yes, whenever the tests pass and there’s something worth shipping.”

Changelog Generation

Since versions don’t encode what changed, the changelog matters more. Our release script generates changelogs from the git log between the previous tag and the current one, using an AI summarizer to produce human-readable release notes.

## v2026.0220.2306

- Added MCP gateway for Model Context Protocol tool calls
- Fixed audit log hash verification on empty logs
- Improved SSH certificate error messages
- Updated dependency: golang.org/x/crypto v0.32.0

The changelog is committed alongside the tag, so every release has a machine-generated but human-readable summary of what changed.

Practical Benefits

In practice, CalVer timestamps have been more useful than SemVer for our use case:

1. Support conversations — “What version are you running?” “v2026.0115.0800” “That’s two months old, upgrade to today’s release” is a more useful exchange than “v1.3.2” “Is that before or after the audit fix?”

2. Deployment auditing — seeing v2026.0115.0800 in a cluster immediately tells you the software hasn’t been updated in months.

3. Release velocity — we release when ready, not when we’ve accumulated enough changes to justify a version bump. Some weeks we release daily; some weeks we don’t release at all. The version scheme doesn’t create pressure either way.