Semantic Versioning Enforcement (DIDP/PPP)
Overview
Semantic versioning (SemVer) provides predictable version numbering that communicates the nature of changes. In the context of protocol publishing, SemVer ensures consumers know when breaking changes occur.
Where SemVer is Enforced
SemVer is enforced in two places:
1. Protocol Publishing (PPP)
- URL includes major version:
/v1,/v2,/v3 - Major bump = breaking changes to the protocol
- Major versions are immutable once published
- Minor/patch changes are documented via errata or metadata
2. Repository CI Checks (Recommended)
- Validate version fields in frontmatter
- Validate tags/releases for protocol versions
- Prevent edits to published major versions unless via errata mechanism
Practical Enforcement Points
| Check | Location | Action |
|---|---|---|
| Frontmatter validation | Pre-commit | Ensure version matches path (v1 => version: "1.x") |
| Immutability check | CI | Fail builds if published versions are modified |
| Release tagging | Git | Tag as spec-didp-v1.0.0, spec-ppp-v1.0.0, etc. |
Version Location Policy
| Version Component | Location | Required |
|---|---|---|
| Major | URL path (/v1) | Yes |
| Minor | Frontmatter metadata | Optional |
| Patch | Frontmatter metadata | Optional |
Errata Policy
When corrections are needed to published specs:
- Do not modify the canonical major page content
- Add errata section at bottom of spec
- Document the correction with date
- Increment patch version in metadata if tracked
Example
# Frontmatter for /spec/didp/v1
---
title: "DIDP v1"
version: "1.0.1" # Major.Minor.Patch
status: "published"
errata:
- date: "2025-01-15"
description: "Clarified phase transition rules"
---
Suggested Policy Summary
- Major in URL: Required for all published specs
- Minor/patch in metadata: Optional, for internal tracking
- Errata: Allowed without changing canonical URL or major version