Versioning

Versioning

Version work products that evolve across iterations: architecture docs, schemas, design specs, research, and any multi-version deliverable.

When to Version

Version when:

• A document/schema/design will be iterated on across sessions
• You're producing multiple revisions of the same artifact
• The user asks for "versioned" output or "version everything"
• Multiple files reference each other and must stay in sync
• You need to track what changed between iterations

Skip versioning for:

• One-shot scripts, quick notes, throwaway output
• Single-file deliverables that won't be revised
• Informal conversation output

Naming Convention

{name}-v{major}.{minor}.{patch}.{ext}

Examples:

• robopartpicker-v1.3.0-architecture.md

• robopartpicker-v1.3.0-schema.sql

• pipeline-v2.1.0-design.md

• Major: architectural changes, incompatible schema changes, new pillars

• Minor: new sections, new tables, expanded coverage

• Patch: fixes, clarifications, typo corrections

VERSIONS.md Manifest

Every versioned project gets a VERSIONS.md in its root directory.

Format:

# {Project Name} — VERSIONS MANIFEST
# Last updated: {date}

================================================================================
ACTIVE FILES (use these)
================================================================================
{file-v2.1.0-architecture.md}    Description
{file-v2.1.0-schema.sql}         Description

================================================================================
VERSION HISTORY
================================================================================
v2.1.0 — {date}
  Changes made
  Output: {files}

v2.0.0 — {date}
  Changes made

v1.0.0 — {date}
  Initial version

================================================================================
SUPERSEDED FILES (kept for reference, prefer v{current})
================================================================================
{file-v1.0.0-research.md}    v1.0 — superseded by v2.1.0

================================================================================
NEXT: v{next} PLANNED
================================================================================
- Planned changes

Document Header Format

Every versioned document starts with:

# {Title}
# Version {X}.{Y}.{Z} | {YYYY-MM-DD}
# Status: {Draft | Review | Final}
# Previous: v{prev} ({brief description})

Followed by a changelog block:

================================================================================
CHANGELOG
================================================================================
v{X}.{Y}.{Z} — {date}
  1. Change one (why)
  2. Change two (why)

v{prev} — {date}
  Prior changes
================================================================================

Superseded File Handling

1. Keep the old file on disk — do NOT delete it
2. Mark it in VERSIONS.md under SUPERSEDED FILES with what supersedes it
3. The ACTIVE FILES section in VERSIONS.md is the single source of truth
4. Old versions preserve the evolution of decisions — they are the paper trail

Standard Workflow

When asked to produce or update versioned output:

1. Check if VERSIONS.md exists. If yes, read it to understand current state.
2. Determine bump:
   • Breaking schema, incompatible redesign → bump MAJOR
   • New sections, new tables, expanded scope → bump MINOR
   • Fixes, clarifications, no structural change → bump PATCH
3. Write new versioned file(s) with proper header + changelog
4. Update VERSIONS.md: move superseded files, add new entries, update NEXT
5. Never delete superseded files

Pitfalls

• Don't version too granularly — version the deliverable, not every edit
• Version number must be in the FILENAME, not just VERSIONS.md
• One VERSIONS.md per project, not per file — multiple files in same release share version number
• Don't forget to update VERSIONS.md when creating a new version — stale manifests cause confusion
• Old unversioned files sitting alongside versioned ones create ambiguity — either version them or move them to an archive directory