Clarify Decision Point Versioning rules (revises ADR 0003 into ADR 0006)

docs/adr/0003-ssvc-decision-point-versioning-rules.md

@@ -1,5 +1,5 @@
 ---
-status: accepted
+status: superseded by [ADR-0006](0006-ssvc-decision-point-versioning-rules.md)
 date: 2023-10-17 
 deciders: adh, jspring, vssarvepalli, latyzenhaus, cgyarbrough, ehatleback
 ---

docs/adr/0006-ssvc-decision-point-versioning-rules.md

@@ -0,0 +1,142 @@
+---
+status: accepted
+date: 2023-11-01
+deciders: adh, jspring
+---
+# SSVC Decision Points Versioning Rules
+
+## Context and Problem Statement
+
+A decision point represents a unit of information for use in one or more decisions
+An SSVC "version" might introduce new decision points or new functions (trees) over existing decision points (or both)
+As SSVC evolves and grows, we occasionally have the need to modify an existing decision point.
+This can happen as we learn more about a particular decision and how a particular decision point is used in practice.
+It can also happen as we refine our understanding of the concept that a decision point represents.
+
+Our expectation is that decision points could go through a number of revisions over time, but that the revisions
+should be relatively infrequent after an initial period of refinement.
+
+Note: This decision addresses the rules for versioning, and depends on the decision to version decision points in the first place.
+
+## Decision Drivers
+
+* Decision points evolve over time
+  * new values (options) are added, modified, or removed
+  * descriptions are updated
+* Semantic versioning is a well-known and well-understood standard, but we need to define how it applies to decision points.
+
+## Considered Options
+
+See SSVC [Discussion #289](https://github.com/CERTCC/SSVC/discussions/289).
+
+Strictly speaking, Decision Points might not need to be explicitly versioned because they're basically static once introduced.
+(Because any semantic change just forks into a new decision point.)
+However, for future-proofing purposes we might want to include a key-value pair in the decision point definition to represent a version ID.
+
+We could establish rules such as
+
+* version 0.x is reserved for pre-support Decision Points and their shorthand key, labels, number of labels, ordering of labels, descriptions, semantics, etc. are all subject to change
+* version 1.0 freezes the Decision Point labels, number of labels, and their ordering
+* version 1.0.x for x > 0 would be limited to description changes
+
+## Decision Outcome
+
+Chosen option: "Semantic versioning":
+
+> Given a version number MAJOR.MINOR.PATCH, increment the:
+>
+> * MAJOR version when you make incompatible API changes
+> * MINOR version when you add functionality in a backward compatible manner
+> * PATCH version when you make backward compatible bug fixes
+>
+> Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.
+
+Applied as follows:
+
+### Create a new object when
+
+* A different or new concept is being represented
+
+**Note**: New objects SHOULD get new names and new keys
+
+### Increment the Major Version when
+
+* Criteria for creating a new object are not met, _AND_
+  * existing values are removed, _OR_
+  * value semantics change in a way that older answers are no longer usable,
+    _OR_
+  * new values are added that divide previous value semantics ambiguously
+
+**Note**: The ability to map old to new semantics is encouraged but not required
+
+### Increment the Minor Version when
+
+Minor version increments imply that existing value semantics are preserved.
+
+* Criteria for incrementing the Major Version are not met, _AND_
+  * new options are added, _OR_
+  * value names or keys are changed, _OR_
+  * the decision point name is changed
+
+### Increment the Patch Version when
+
+Patch version increments imply that existing value number and semantics are
+preserved.
+
+* Criteria for incrementing the Major or Minor Version are not met, _AND_
+  * typo fixes in option names or decision point name, _OR_
+  * the decision point description changes in a way that does not affect 
+    semantics, _OR_
+  * a value description changes in a way that does not affect semantics
+
+### Pre-Support Decision Points
+
+Decision Points having a major version of 0 are considered to be pre-support
+and their shorthand key, labels, number of labels, ordering of labels,
+descriptions, semantics, etc. are all subject to change.
+
+Because the Major Version is 0 for these decision points, the Minor Version
+and Fix Version can be used to indicate how significant a change is by
+combining the above rules for Major and Minor versions into a single rule for
+Minor versions.
+In other words, a Minor version increment of a 0.x decision point may be used
+to indicate a change in semantics that is not backwards compatible.
+This is not the case for decision points with a Major Version of 1 or greater.
+
+The lowest _supported_ version of a decision point is 1.0.0.
+
+### Examples
+
+We use CVSS Attack Vector (formerly Access Vector) as an example because it
+illustrates the ambiguity that can arise when a decision point value is split.
+
+| Decision Point                  | Initial Version | New Version | Reason                                         |
+|---------------------------------| --------------- |-------------|------------------------------------------------|
+| Access Vector                   | 1.0.0           | 2.0.0       | `remote` split into `network` and `adjacent`   |
+| Attack (formerly Access) Vector | 2.0.0           | 3.0.0       | `local` split into `physical` and `local` |
+
+We observe that if the only change was from Access Vector v2.0.0 being
+renamed to Attack Vector, then the new version would have been 2.1.0. However,
+the change in semantics from Local to Physical and Local is not backwards
+compatible, so the new version is 3.0.0.
+
+### Consequences
+
+* Maintaining version numbers for decision points according to these rules will add a small burden to each decision point.
+* Semantic versioning will make it easier to track changes to decision points over time.
+* Because we don't anticipate frequent changes to decision points, the burden of maintaining version numbers should be minimal.
+* Decision point versions can move in either direction when used repeatedly in other versioned objects (E.g., a decision model could
+use use version 2.1 of a decision point at one time and later revert to using version 1.0 if the 2.1 was found to be problematic).
+* Multiple versions of decision points will be "live and available for use" by folks modeling decisions unless explicitly deprecated.
+* We think that Decision Points SHOULD have a way to indicate a deprecated status as a means to stave off future regrets.
+This implies the need for a way to denote the _status_ of a decision point in addition to its _version_.
+Decision Point _status_ will need to be addressed in a separate decision (or decisions) regarding decision point lifecycles.
+
+### Confirmation
+
+* The PR process will confirm that the decision point version number is updated according to these rules.
+
+## More Information
+
+* [Discussion #289](https://github.com/CERTCC/SSVC/discussions/289) in the SSVC project.
+* [Semantic Versioning](https://semver.org/)