Story: Clarify versioning strategy
Table of Contents
This page documents a story in Sprint 19. It captures the goal, current status, acceptance criteria, and the tasks that compose it.
Goal
Resolve the naming confusion between a version series (v0, v1 — the 0.x.x / 1.x.x release containers) and a major release target (v1.0, v2.0 — what closes the series). Introduce milestone as the first-class concept that owns identity, theme, mission, and DoD. Versions become lean containers: release series, sprints, and a pointer to their target milestone.
Status
| Field | Value |
|---|---|
| State | DONE |
| Parent sprint | Sprint 19 |
| Now | Nothing. |
| Waiting on | Nothing. |
| Next | Merge PR #1000. |
| Last touched | 2026-06-02 |
Acceptance
doc/agile/milestones/exists withmilestones.org,v1.org,v2.org.milestones.orgexplains the milestone/version distinction with a comparison table.v0/version.orgis lean: no identity/mission/DoD; points to Milestone v1.0.agile.organdversions.orglink to milestones.- Glossary has a
Milestoneentry;Versionentry corrected.
Tasks
| Task | State | Start | End | Description |
|---|---|---|---|---|
| Create milestones infrastructure | DONE | 2026-06-02 | 2026-06-02 | Scaffold milestones dir, catalogue, v1.org, v2.org; update glossary. |
| Slim v0/version.org | DONE | 2026-06-02 | 2026-06-02 | Strip identity/mission/DoD; add milestone pointer. |
| Wire milestones into index docs | DONE | 2026-06-02 | 2026-06-02 | Link from agile.org and versions.org; At a glance row. |
Decisions
- Milestone docs use
#+type: knowledgefor now; a dedicatedmilestonecompass type is a future improvement. - Version 1 row in milestones catalogue is plain text (no org-roam link) until
v1/version.orgis created.
Out of scope
- Renaming the
v0/directory — the directory name correctly matches the 0.x.x release series. - Creating
v1/version.org— deferred until v1 work begins.