From e80cf18cc271b7ea23263c6744cfe42e0df9acf0 Mon Sep 17 00:00:00 2001 From: JarbasAi Date: Sat, 4 Jul 2026 14:14:01 +0100 Subject: [PATCH] =?UTF-8?q?spec:=20VERSIONING.md=20=E2=80=94=20define=20Ve?= =?UTF-8?q?rsion=20(compatibility=20class)=20vs=20Revision=20(within-class?= =?UTF-8?q?=20edit=20counter)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- VERSIONING.md | 24 +++++++++++++++++++++--- 1 file changed, 21 insertions(+), 3 deletions(-) diff --git a/VERSIONING.md b/VERSIONING.md index 8906efe..49df34f 100644 --- a/VERSIONING.md +++ b/VERSIONING.md @@ -19,9 +19,27 @@ 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`). ## The 1.0 definition