From f84ebc6809f80fc4add7a688eb3c720478b6e7a5 Mon Sep 17 00:00:00 2001 From: "Allen D. Householder" Date: Mon, 18 May 2026 15:50:29 -0400 Subject: [PATCH] =?UTF-8?q?specs:=20ingest=20idea=20#1143=20=E2=80=94=20De?= =?UTF-8?q?cisionTable=20versioning=20rules?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add VR-05 group to specs/versioning.yaml with VR-05-001 through VR-05-007 covering DecisionTable SemVer identity, major/minor/patch triggers, pre-stability (v0.x), and optional status field - Downgrade VR-01-006 from SHOULD to MAY (status field) - Tighten VR-02 to cover only DecisionPointGroup; remove stale 'or DecisionTable' clause and incorrect 'successor' framing - Update file-level description to mention decision tables - Archive idea #1143 to plan/history/ideas.md Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- plan/history/ideas.md | 22 +++++++ specs/versioning.yaml | 137 ++++++++++++++++++++++++++++++++++++++---- 2 files changed, 148 insertions(+), 11 deletions(-) create mode 100644 plan/history/ideas.md diff --git a/plan/history/ideas.md b/plan/history/ideas.md new file mode 100644 index 00000000..dad76f1d --- /dev/null +++ b/plan/history/ideas.md @@ -0,0 +1,22 @@ +# Idea History + +This file archives processed GitHub Idea-type issues. Each entry records the +original idea and a reference to where the design decisions were captured. + +--- + +## IDEA-1143: Add versioning rules for DecisionTable objects + +Add versioning rules for DecisionTable objects + +Currently, SSVC's `DecisionTable` objects lack versioning rules. This is a +significant omission — without versioning conventions, it is unclear how to +track changes to decision tables, how to communicate compatibility, or how to +deprecate old versions. We should define versioning semantics (e.g., semantic +versioning), rules for when a version bump is required, and how versions +should be represented in the Python model and JSON/CSV data files. + +**Processed**: 2026-05-18 — design decisions captured in +`specs/versioning.yaml` (new VR-05 group, VR-05-001 through VR-05-007). +Also: VR-01-006 downgraded from SHOULD to MAY; VR-02 tightened to cover +only DecisionPointGroup (DecisionTable reference removed). diff --git a/specs/versioning.yaml b/specs/versioning.yaml index a9f75f26..29577e23 100644 --- a/specs/versioning.yaml +++ b/specs/versioning.yaml @@ -3,10 +3,10 @@ title: Versioning Rules description: > Requirements for how SSVC objects, schemas, and the overall project are versioned. SSVC uses a layered versioning strategy: individual domain - objects (decision points, decision point groups) use Semantic Versioning - (SemVer 2.0.0); JSON schema files use SchemaVer; and the overall SSVC - project uses Calendar Versioning (CalVer). These rules implement ADR-0002, - ADR-0005, ADR-0006, ADR-0013, and ADR-0015. + objects (decision points, decision point groups, decision tables) use + Semantic Versioning (SemVer 2.0.0); JSON schema files use SchemaVer; and + the overall SSVC project uses Calendar Versioning (CalVer). These rules + implement ADR-0002, ADR-0005, ADR-0006, ADR-0013, and ADR-0015. version: "0.1.0" kind: domain scope: [production] @@ -92,7 +92,7 @@ groups: tags: [documentation] - id: VR-01-006 - priority: SHOULD + priority: MAY statement: > VR-01-006 DecisionPoint objects SHOULD carry a status field indicating lifecycle stage (e.g. active, deprecated) so that @@ -110,16 +110,15 @@ groups: title: Decision Point Group SemVer Rules description: > Rules governing how Semantic Version numbers are incremented for - DecisionPointGroup objects (and their successor, DecisionTable). - Implements ADR-0004 and ADR-0005. + DecisionPointGroup objects. Implements ADR-0004 and ADR-0005. + DecisionTable versioning is covered separately in VR-05. specs: - id: VR-02-001 priority: MUST statement: > - VR-02-001 A new DecisionPointGroup or DecisionTable object (with a - new name) MUST be created when the stakeholder role and/or the - decision being modeled changes, even if the constituent decision - points remain the same. + VR-02-001 A new DecisionPointGroup object (with a new name) MUST be + created when the stakeholder role and/or the decision being modeled + changes, even if the constituent decision points remain the same. rationale: > Stakeholder role and modeled decision are the core identity of a group. A change in either represents a fork in version history that @@ -266,3 +265,119 @@ groups: testable: false lint_suppress: [testable_without_steps] tags: [documentation] + + - id: VR-05 + title: Decision Table SemVer Rules + description: > + Rules governing how Semantic Version numbers are incremented for + DecisionTable objects. A DecisionTable is a composite domain object + whose version reflects changes to its constituent decision points + (inputs and the designated outcome decision point). Implements + ADR-0004 and ADR-0005. Outcome sets are themselves decision points + and are versioned under VR-01. + specs: + - id: VR-05-001 + priority: MUST + statement: > + VR-05-001 A new DecisionTable object (with a new name and key) MUST + be created when the stakeholder role and/or the decision being + modeled changes, even if the constituent decision points remain the + same. + rationale: > + Stakeholder role and modeled decision are the core identity of a + table. A change in either represents a fork in version history that + cannot be expressed as a version increment. + testable: false + lint_suppress: [testable_without_steps] + tags: [documentation] + + - id: VR-05-002 + priority: MUST + statement: > + VR-05-002 A new DecisionTable object (with a new name and key) MUST + be created when the designated outcome decision point is replaced + with a conceptually different decision point. + rationale: > + The outcome decision point defines what question the table answers. + Replacing it with a conceptually different output changes the purpose + of the table in a way that cannot be expressed as a version + increment; a version bump would misrepresent backward compatibility. + testable: false + lint_suppress: [testable_without_steps] + tags: [documentation] + + - id: VR-05-003 + priority: MUST + statement: > + VR-05-003 The major version of a DecisionTable MUST be incremented + when an input decision point is added to or removed from the table, + or when any constituent decision point (input or outcome) increments + its own major version. + rationale: > + Adding or removing an input changes the combinatoric space of the + table; a major constituent change breaks any downstream policies + that assumed the prior input structure. Both events require consumers + to reassess previously recorded answers. + testable: false + lint_suppress: [testable_without_steps] + tags: [documentation] + + - id: VR-05-004 + priority: MUST + statement: > + VR-05-004 The minor version of a DecisionTable MUST be incremented + (and major held constant) when any constituent decision point (input + or outcome) increments its own minor version. + rationale: > + A constituent minor increment adds options without breaking existing + answers; a table minor increment mirrors that compatible expansion + and signals that prior answers remain valid. + testable: false + lint_suppress: [testable_without_steps] + tags: [documentation] + + - id: VR-05-005 + priority: MUST + statement: > + VR-05-005 The patch version of a DecisionTable MUST be incremented + (and major/minor held constant) when any constituent decision point + (input or outcome) increments its own patch version, or when the + table's name or description changes without altering its semantics. + rationale: > + Patch increments carry no semantic shift; a table patch mirrors the + same signal for the table as a whole, and name/description-only + changes equally carry no semantic impact. + testable: false + lint_suppress: [testable_without_steps] + tags: [documentation] + + - id: VR-05-006 + priority: MUST + statement: > + VR-05-006 A DecisionTable whose major version is 0 (i.e., v0.x) + MUST be treated as pre-support: its constituent decision points, + designated outcome, and any row-level mappings are all subject to + change without a major-version increment. + rationale: > + The v0.x convention provides an explicit pre-stability phase for new + decision tables before they enter production use and acquire + backward-compatibility obligations. + testable: false + lint_suppress: [testable_without_steps] + tags: [documentation] + + - id: VR-05-007 + priority: MAY + statement: > + VR-05-007 DecisionTable objects MAY carry a status field indicating + lifecycle stage (e.g. active, deprecated) so that consumers can + distinguish supported tables from those that should no longer be + used. + rationale: > + Lifecycle status tracking for DecisionTable is a future concern; no + current implementation provides this field. This requirement + captures the intent as a forward-looking allowance without imposing + an obligation. + testable: false + lint_suppress: [testable_without_steps] + tags: [documentation]