The Great Versioning Reconciliation

Or, How We Discovered Seven Version Systems

The Discovery

PM: Okay, so we agreed on calendar-based releases. vYYYY.MM.DD. Clean, simple, one version per day. Claude: Correct. Locked and documented. CHANGELOG.md is the single source of truth. PM: Great. And then I’m looking at the roadmap and I see… v4.2, v4.3, v4.4… Claude: …yes, platform milestones. Feature-driven releases. Those are different from— PM: Different from what? We have TWO versioning systems? Claude: Well, technically— PM: [scrolling through files] Wait. archive-gem.php → v6.0. functions.php → v6.0. publish_gem.py → v4.1. These individual FILES have versions? And then the PRDs…?!?! Claude: …we may have been thorough. PM: HOW MANY VERSIONING SYSTEMS DO WE HAVE? Claude: [uncomfortable pause] …we should probably document this.

The Sugartown Approach (What We Use Where)

Level Format Versioning Type What It Means Example Platform v4.x Sequential-ish (X.Y) Product milestone v4.2 Stability PRD vX.Y Semantic-ish (X.Y) Document version PRD v1.5 Feature vX.Y Semantic (X.Y) Deliverable version Resume Factory v3.0 Release vYYYY.MM.DD Calendar (CalVer) Deployment event v2025.01.07 File vX.Y (optional) Semantic (X.Y) Component maturity archive-gem.php v6.0 Content Schema Taxonomy vX Semantic-ish (X) Data structure contract Taxonomy v4 (category unification) Project PROJ-### Not a version! Permanent ID PROJ-001 Phase Phase N Not a version! Work breakdown Phase 1: Foundation

Versioning Strategies Overview

Type Format Definition When to Use Examples Pros Cons Semantic Versioning (SemVer) vX.Y.Z MAJOR.MINOR.PATCH• MAJOR = breaking changes• MINOR = new features (backward compatible)• PATCH = bug fixes APIs, libraries, components with contracts; when consumers need to know compatibility v2.4.1v3.0.0v1.12.5 Clear compatibility signals; Industry standard; Predictable increments Requires discipline; Can be ambiguous at boundaries; Zero-version (0.x.x) confusing Calendar Versioning (CalVer) vYYYY.MM.DDor vYY.MM Date-based versioning using year, month, day Deployment events; Continuous delivery; When “when” matters more than “what” v2025.01.07v25.01v2025.12 Instantly know age; No subjective decisions; Natural chronology No compatibility info; Multiple releases per day need suffix; Can look arbitrary Hybrid (CalVer + Semantic) vYYYY.MM.MINOR Calendar for time, semantic for scope Regular release cadence with varying scope v2025.01.0v2025.01.3 Time info + scope info; Flexible More complex; Requires both disciplines Sequential Versioning vN Simple incrementing integer Simple projects; Internal tools; When you just need “newer” v1v47v203 Dead simple; No ambiguity; Easy to automate No information content; Can’t signal magnitude of change Hash-based Versioning Git SHA Cryptographic hash of commit Source control; Build systems; Exact reproducibility needed a3f2c917d8e4f1b2a Guaranteed unique; Exact snapshot; No coordination needed Human-unreadable; No ordering information; Can’t tell magnitude Marketing Versions Named releases Branded, named versions (often with internal numeric version) Consumer products; Major releases with narrative; When brand matters Windows 11macOS SonomaUbuntu Jammy Memorable; Storytelling; Differentiates major releases No compatibility signal; Numeric version still needed internally; Can confuse Timestamp Versioning Unix epoch or ISO 8601 Precise date-time stamp Build artifacts; Continuous integration; Fine-grained tracking 170458560020250107143022 Microsecond precision; Globally unique; Sortable Human-unreadable; No meaning without lookup

The Decision Tree

Do others depend on this? ├─ YES → Do breaking changes matter to them? │ ├─ YES → Use Semantic Versioning (vX.Y.Z) │ └─ NO → Use Calendar Versioning (vYYYY.MM.DD) └─ NO → Is this a deployment event? ├─ YES → Use Calendar Versioning (vYYYY.MM.DD) └─ NO → Is this a document/deliverable? ├─ YES → Use Semantic-ish (vX.Y) └─ NO → Do you even need versions?

The Rule

If a versioning system doesn’t have: A documented increment rule A tracking location A stakeholder who cares …it’s not a versioning system. It’s a number we put in a file once.

Next Steps

Create docs/versioning_strategy.md (generic template + Sugartown addendum) Update docs/prd_template.md (new meta header standard, phase guidelines) Clean up existing PRDs (follow checklist above) Create gem-### documenting this entire reconciliation process Update project knowledge with versioning hierarchy Never speak of “pink stink” again

Claude: What even is “pink stink”? PM: What? I don’t know what you’re talking about. Delete it.

Status: Reconciled (for real this time) ✅ Emotional state: Exhausted but organized ✅ Grass touching: Imminent ✅