Package Versioning

Overview

We follow a Zero-Major Versioning philosophy, which is a deliberate variation of Semantic Versioning (SemVer). This approach keeps the major version permanently at 0 while using the middle and last digits differently than traditional SemVer.

The 0.Y.Z Format

Our version format is: 0.Y.Z

Position	Meaning	Increments When
0	Epoch/Era indicator (fixed)	Never - we opt out of SemVer's major signaling
Y	Breaking-ish changes	API changes that may break existing integrations
Z	Everything else	New features, bug fixes, patches - all non-breaking changes

Think of it as: 0.MAJOR.MINOR+PATCH

• 0 = We opt out of SemVer's normal 'major' signaling
• Y (second number) = Breaking changes (what SemVer would put in MAJOR)
• Z (third number) = Features and fixes combined

Why Zero-Major?

The Zero-Major approach avoids the "marketing weight" of major version bumps (v1 → v2 → v3) while still communicating breaking changes effectively. It acknowledges that:

1. Major version changes carry psychological weight - jumping from v1 to v2 suggests a major overhaul
2. Breaking changes are normal - they shouldn't require a "major release marketing event"
3. Simplicity - one stream for breaking changes, one stream for everything else

Version Bump Examples

Non-Breaking Changes (Bump Z)

For features, fixes, patches, and any backward-compatible changes:

0.65.3 → 0.65.4  (bug fix)
0.65.4 → 0.65.5  (new feature)
0.65.5 → 0.65.6  (documentation update)

Breaking Changes (Bump Y, Reset Z)

For API changes, deprecations, or anything that might break existing integrations:

0.65.3 → 0.66.0  (breaking API change)
0.66.0 → 0.67.0  (another breaking change)

Decision Flowchart

Practical Guidelines

What counts as "breaking"?

• Removing or renaming public API endpoints
• Changing required parameters or their types
• Modifying response formats in incompatible ways
• Removing features that consumers might depend on
• Changes to authentication or authorization behavior

What counts as "non-breaking"?

• Adding new API endpoints
• Adding optional parameters
• Bug fixes that don't change expected behavior
• Performance improvements
• Adding new features
• Documentation updates
• Internal refactoring

Comparison with Traditional SemVer

Aspect	Traditional SemVer	Our Zero-Major
Format	MAJOR.MINOR.PATCH	0.Y.Z
Breaking changes	Bump MAJOR	Bump Y
New features	Bump MINOR	Bump Z
Bug fixes	Bump PATCH	Bump Z
Major version	Changes frequently	Always 0

Summary

In Zero-Major Versioning:

1. The first digit is always 0 - we opt out of major version signaling
2. The second digit (Y) signals breaking changes - bump it when you might break something
3. The third digit (Z) is everything else - features and fixes share this counter

This approach gives us the benefits of communicating breaking changes without the overhead of managing major versions.