Epoch Semantic Versioning (Epoch SemVer)

Epoch SemVer is a versioning scheme that extends standard Semantic Versioning by introducing a fourth logical component: the epoch. It is designed for environments that need to represent rare, high-signal generational shifts that are more significant than ordinary major-version updates, while remaining compatible with existing SemVer tooling.

How it Works

Epoch SemVer maintains a logical four-part version tuple (epoch, major, minor, patch) but encodes it into a standard three-part SemVer string using a fixed multiplier of 1000.

The Encoding Formula

The external "Major" version is calculated as: encodedMajor = epoch * 1000 + major

Examples:

• Logical: (0, 2, 4, 1) \rightarrow Encoded: 2.4.1
• Logical: (1, 0, 0, 0) \rightarrow Encoded: 1000.0.0
• Logical: (1, 3, 2, 0) \rightarrow Encoded: 1003.2.0

Logical Components

Component	Meaning	Significance
Epoch	Rare generational or landmark changes	Highest
Major	Ordinary breaking changes	High
Minor	Backwards-compatible additions	Medium
Patch	Backwards-compatible fixes	Lowest

Key Rules

• Incrementing: When incrementing a component, all less-significant components must be reset to 0 (e.g., incrementing the epoch resets major, minor, and patch).
• Major Range: The logical major version must be between 0 and 999.
• Codenames: When epoch > 0, a human-friendly codename (e.g., "obsidian") is required to identify the current epoch.
• Pre-releases: Standard SemVer pre-release identifiers are supported and handled according to standard SemVer precedence rules.

Canonical Versioning

To ensure a single source of truth, every versioned unit must have a canonical file named epoch-version.json. This file contains the logical version components and release metadata (such as releasedAt and commitHash).

Supported Repository Policies:

• Independent-version: Each unit has its own epoch-version.json.
• Shared-version: One epoch-version.json governs multiple units.