From cb581b26fa584f18f5148dcf721b1c698582e370 Mon Sep 17 00:00:00 2001 From: JarbasAi Date: Tue, 4 Aug 2026 13:51:00 +0100 Subject: [PATCH] =?UTF-8?q?spec:=20VERSIONING.md=20=E2=80=94=20Version=20?= =?UTF-8?q?=3D=20compatibility=20class,=20Revision=20=3D=20within-class=20?= =?UTF-8?q?edit=20counter?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Squashed from: - spec: VERSIONING.md — applicability names the lever for pre-Revision specs - docs: scope VERSIONING split as policy-only with lazy header migration - spec: VERSIONING.md — define Version (compatibility class) vs Revision (within-class edit counter) Co-Authored-By: Claude Fable 5 --- VERSIONING.md | 47 ++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 44 insertions(+), 3 deletions(-) diff --git a/VERSIONING.md b/VERSIONING.md index 8906efe2..524a6556 100644 --- a/VERSIONING.md +++ b/VERSIONING.md @@ -19,9 +19,50 @@ V2. The classification is part of the spec header. Rules of thumb: - A single spec MAY contain V1 sections and V2 sections only if the V2 parts are explicitly gated (configuration flag) and the ungated behavior is V1. -Within a class, editorial revisions bump the spec's own revision number in -its header; compatibility class changes (V1 → V2) are a new spec version, not -a revision. +## Version and Revision + +Every spec header carries two fields: + +- **`Version`** — the spec's V0/V1/V2 **compatibility class** as defined + above. It answers exactly one question: is this contract backwards + compatible with the pre-spec status quo? A change to normative content + that does not alter that answer MUST NOT change `Version`. +- **`Revision`** — a monotonic **within-class edit counter**, starting at + `1` for the class's first published text. Every pull request that alters + a spec's normative content MUST increment its `Revision` by one. + Non-normative edits (typo and formatting fixes, cross-reference + corrections, examples) MUST NOT increment it. + +A refinement — tightening a requirement, adding an optional field, +clarifying a contract while the compatibility class stays intact — bumps +`Revision`, not `Version`. `Version` changes only when the edit changes +the compatibility class itself (e.g. a V1 spec adopts a rename that breaks +V0 consumers → `Version: 2`); a `Version` change resets `Revision` to `1` +for the new class. A spec is cited by class (`OVOS-MSG-1 v1`); `Revision` +disambiguates which text of that class is meant (`v1 rev 3`). + +## Applicability + +This document is policy-only: it does not itself amend any spec header. A +spec header gains its `Revision` field lazily, in that spec's next +substantive pull request, not through a bulk migration across the repository. + +Until a spec's header carries a `Revision` field, `Version` remains the only +lever available for any normative change to that spec — including a +refinement that, under the Version/Revision split above, would otherwise be +`Revision`-only. A spec SHOULD gain `Revision: 1` the first time such a +refinement lands, so that the split applies to it going forward; the pull +request that adds the field records the refinement as the class's next +`Version` bump per the pre-split convention, exactly as CHANGELOG.md already +groups every entry under its spec's `### N` (`Version`) heading, never under +a `Revision` subheading. + +Once a spec carries `Revision`, the Version/Revision split above governs: +Version changes only when the edit changes the compatibility class itself; +prose, example, citation, or scope refinements that leave the class intact +bump Revision instead. Until a spec carries `Revision`, its prior `Version` +history MUST be read under the old single-counter policy that predates this +document. ## The 1.0 definition