Why CalVer

Yew Search uses Calendar Versioning (CalVer) instead of Semantic Versioning (SemVer) for its release versioning strategy.

What is CalVer?

Calendar Versioning is a versioning convention based on your project's release calendar instead of arbitrary version numbers. Our format is:

YYYY.MM.DD.patch

Examples:

• 2025.01.27.0 - First release on January 27, 2025
• 2025.01.27.1 - Hotfix released same day
• 2025.02.15.0 - Release on February 15, 2025

Why Not SemVer?

Semantic Versioning (MAJOR.MINOR.PATCH) is excellent for libraries and APIs where backward compatibility matters to consumers. It communicates:

• MAJOR - Breaking changes
• MINOR - New features, backward compatible
• PATCH - Bug fixes only

However, for full-stack, self-hosted applications like Yew Search, SemVer's semantic signaling creates unnecessary overhead:

SemVer Limitations for Self-Hosted Apps

1. Meaningless for Coordinated Deployments

   • You deploy frontend and backend together
   • No external consumers need compatibility guarantees
   • "Is this a minor or major change?" becomes bikeshedding

2. Artificial Version Inflation

   • Breaking UI changes → MAJOR bump → v7.0.0
   • Adds feature → MINOR bump → v7.1.0
   • Fixes bug → PATCH bump → v7.1.1
   • Numbers grow arbitrarily with no real meaning

3. No Time Context

   • Looking at v3.2.7 tells you nothing about when it was released
   • Was this last week or 2 years ago?
   • Which version should I use in production?

CalVer Benefits for Yew Search

1. Deployment Age is Immediately Visible

# Which is newer?
backend:2025.01.27.0  vs  backend:2025.01.20.0  ← Obviously the 27th

# SemVer equivalent:
backend:v2.3.1  vs  backend:v2.2.9  ← Need to look up release notes

2. "Which Version is Newer?" is Always Obvious

With CalVer, date comparison is intuitive:

• 2025.02.15.0 > 2025.01.27.0 (February > January)
• 2025.01.27.1 > 2025.01.27.0 (same day, higher patch)

No need to remember if v2.9.0 came before or after v2.10.0.

3. Aligns with Docker Image Lifecycles

Container images are tagged with build dates by default:

• You already track "when was this built"
• CalVer makes the version tag match that mental model
• Easy to correlate deployment date with release version

4. No Semantic Overhead

You don't waste time debating:

• "Is changing the search UI a major or minor version bump?"
• "Does fixing this edge case count as a patch?"
• "Should we bump to v2.0.0 for this refactor?"

Just release it. The date is the version.

5. Matches User Mental Model

Users think in terms of:

• "I'm running the January 27th release"
• "We need to upgrade to last week's version"
• "Roll back to the January 20th deployment"

Not:

• "What features are in v2.3.0 vs v2.2.0?"
• "Is v3.0.0 stable yet?"

6. Simplifies Production Rollback

When you need to roll back:

# CalVer: Know exactly what you're rolling back to
docker pull backend:2025.01.20.0  # Last week's stable version

# SemVer: Need to remember which version was stable
docker pull backend:v2.7.3  # Was this the good one or v2.7.2?

Real-World Examples

Many successful projects use CalVer for similar reasons:

Project	CalVer Format	Type
Ubuntu	YY.MM (e.g., 24.04)	Operating System
Bolt	YYYY.0M.MICRO	JavaScript toolchain
pip	YY.MINOR	Python package installer
Unity	YYYY.MINOR.MICRO	Game engine
Twisted	YY.MM.MICRO	Python networking framework

These are all full applications or platforms, not libraries.

CalVer vs SemVer Comparison

Aspect	CalVer	SemVer
Best for	Applications, platforms, releases	Libraries, APIs, packages
Communicates	When it was released	What changed
Version comparison	Trivial (date math)	Requires context
Breaking changes	Don't need special signaling	MAJOR version bump
Coordinated releases	Natural (same date)	Artificial (same major)
Time context	Built-in	Requires changelog
Versioning debates	None	Frequent

When We Increment Version Numbers

Increment Date (YYYY.MM.DD)

• Every new deployment day
• Even if it's just one commit
• Example: 2025.01.27.0 → next day → 2025.01.28.0

Increment Patch (.patch)

• Multiple releases on the same day
• Usually for hotfixes or urgent deployments
• Example: 2025.01.27.0 → hotfix → 2025.01.27.1

Special Tags

• :latest - Always the newest release (any date)
• :2025 - Latest release from 2025
• :develop - Latest develop branch build (optional)

Migration from :latest

Existing Yew Search deployments use :latest tags. Migrating to CalVer is opt-in:

Current:

backend:
  image: registry.gitlab.com/your-namespace/yew-monorepo/backend:latest

With CalVer (recommended for production):

backend:
  image: registry.gitlab.com/your-namespace/yew-monorepo/backend:2025.01.27.0

Why pin to CalVer in production?

• :latest auto-updates on restart (can break unexpectedly)
• CalVer pins to specific, tested release
• You control when to upgrade (test in staging first)

FAQs

Q: What if we make multiple breaking changes in one day? A: Doesn't matter - they're all in the same release (2025.01.27.0). Users upgrade once.

Q: How do we communicate breaking changes to users? A: Changelog, release notes, and migration guides - same as with SemVer, but without artificial version bumps.

Q: Can we mix CalVer and SemVer? A: Not recommended. Pick one versioning strategy and stick with it for consistency.

Q: What about pre-releases or alpha/beta versions? A: Use suffixes: 2025.01.27.0-alpha, 2025.01.27.0-beta, 2025.01.27.0-rc1

Q: Do we need CalVer for every commit? A: No - version only when you officially release. Use :latest or commit SHAs for development builds.

Conclusion

For Yew Search - a self-hosted, full-stack application where frontend and backend are deployed together - CalVer provides:

• Clarity over semantic complexity
• Time context over version arithmetic
• Simplicity over artificial version inflation
• User-friendly versioning over developer-centric numbering

The version tells you when it was released, and that's what matters most for deployment decisions.

---

Learn more: calver.org