Add Decision Point Group Versioning ADRs (#368)

* add adrs

* typo fix

* make logic explicit

* indent logic in lieu of parentheses

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

* revise ADR 0003 into ADR 0006

* fix header

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/0004-ssvc-decision-point-groups-are-versioned.md

@@ -0,0 +1,55 @@
+---
+# These are optional elements. Feel free to remove any of them.
+status: "accepted"
+date: 2023-10-31
+deciders: adh, jspring, vssarvepalli, cgyarbrough, latyzenhaus, ehatleback
+---
+# Decision Point Groups are Versioned using SemVer
+
+## Context and Problem Statement
+
+Decision Point Groups are sets of decision points pinned to specific versions of those decision points.
+These groups may change over time.
+
+For example, the SSVC _Patch Applier_ and _Deployer_ trees have evolved as follows:
+
+| _Patch Applier_ (SSVC v1) | _Deployer_ (SSVC v2)                                      |                   _Deployer_ (SSVC v2.1)                    |
+|:-------------------------:|:--------------------------------------------------------:|:-----------------------------------------------------------:|
+| Exploitation 1.0.0        | Exploitation 1.0.0                                        |                     Exploitation 1.0.0                      |
+| System Exposure 1.0.0     | System Exposure 1.0.1                                     |                    System Exposure 1.0.1                    |
+| Mission Impact 1.0.0      | Mission Impact 1.0.0<br/>(as input to Human Impact 1.0.0) |  Mission Impact 2.0.0<br/>(as input to Human Impact 1.0.0)  |
+| Safety Impact 1.0.0       | Safety Impact 1.0.0<br/>(as input to Human Impact 1.0.0)  |  Safety Impact 1.0.0<br/>(as input to Human Impact 1.0.0)   |
+| -                         | Automatable 1.0.0<br/>(as input to Utility 1.0.1)         |                      Automatable 1.0.0                      |
+| -                         | Value Density 1.0.0<br/>(as input to Utility 1.0.1)       |                              -                              |
+
+We need to be able to discriminate between different versions of these groups.
+
+## Decision Drivers
+
+- Decision Points change over time
+- The composition of decision point groups change over time
+- It is important that we can discriminate between versions of decision point groups
+- Although technically a Decision Point Group is fully defined by the set of pinned Decision Points it contains
+(e.g., any column in the table above), we find it convenient to be able to refer to the group as a whole, and to be
+able to discriminate between different versions of the group.
+
+## Considered Options
+
+- No versioning
+- [Semantic Versioning](https://semver.org/)
+- [CalVer](https://calver.org/)
+
+## Decision Outcome
+
+Chosen option: "Semantic Versioning", because it conveys the magnitude of changes to decision point groups, and provides
+indication of compatibility expectations between versions.
+
+### Consequences
+
+- Maintaining version numbers for decision point groups will add a small burden to each decision point group.
+- Semantic versioning will make it easier to track changes to decision point groups over time.
+- Because we don't anticipate frequent changes to decision point groups, the burden of maintaining version numbers should be minimal.
+
+## More Information
+
+- [Github Discussion #303](https://github.com/CERTCC/SSVC/discussions/303)

docs/adr/0005-ssvc-decision-point-group-versioning.md

@@ -0,0 +1,113 @@
+---
+# These are optional elements. Feel free to remove any of them.
+status: "accepted"
+date: 2023-10-31
+deciders: adh, jspring, vssarvepalli, cgyarbrough, latyzenhaus, ehatleback
+---
+# Decision Point Group Versioning Rules
+
+## Context and Problem Statement
+
+[ADR 004](./0004-ssvc-decision-point-groups-are-versioned.md) established that Decision Point Groups should be versioned.
+
+This ADR establishes the rules for versioning Decision Point Groups.
+
+## Decision Drivers
+
+(See [ADR 004](./0004-ssvc-decision-point-groups-are-versioned.md) for additional context.)
+
+- Decision Points change over time
+- The composition of decision point groups change over time
+- It is important that we can discriminate between versions of decision point groups
+- Although technically a Decision Point Group is fully defined by the set of 
+  pinned Decision Points it contains, we find it convenient to be able to 
+  refer to the group as a whole, and to be able to discriminate between different versions of the group.
+
+
+## Considered Options
+
+A number of options were discussed in
+[SSVC Discussion #303](https://github.com/CERTCC/SSVC/discussions/303).
+
+Summarizing that discussion:
+
+- No versioning
+- [Semantic Versioning](https://semver.org/) of SSVC as a whole (status quo)
+- [Semantic Versioning](https://semver.org/) of individual decision point groups
+- [CalVer](https://calver.org/)
+
+## Decision Outcome
+
+Chosen option: "Semantic Versioning of individual decision point groups",
+because it conveys the magnitude of changes to decision point groups, and
+provides indication of compatibility expectations between versions.
+
+Implemented as follows:
+
+The core identity of a decision point group is derived from the pairing of the
+_stakeholder role_ and the specific _decision_ being modeled.
+
+### Create a new object when
+
+- The stakeholder role and/or the decision being modeled changes. Even if the
+set of decision points remains the same, a shift in either stakeholder role or
+the decision represents a branching in the version history.
+
+**Note:** New objects MUST have a new name.
+
+Otherwise, a change (add, remove) in decision point groups where both the
+role and decision being modeled are held constant SHOULD be given a new
+version of the existing name according to the following rules.
+
+### Increment the major version when
+
+- Conditions for creating a new object are not met, AND
+  - Adding or removing a decision point entirely, OR
+  - An existing decision point increments its major version
+
+### Increment the minor version when
+
+- Conditions for incrementing the major version are not met, AND
+- An existing decision point increments its minor version
+
+### Increment the patch version when
+
+- Conditions for incrementing the minor version are not met, AND
+  - An existing decision point increments its patch version, OR
+  - The decision point group description changes, OR
+  - The decision point group name changes
+
+### Examples
+
+Assume a decision point group (DPG) named _DPG v1.0.0_,
+containing decision points (DP) _A v1.0.0_ and _B v1.3.1_.
+In the table below, we show how the Decision Point Group version number changes
+as the constituent Decision Points change.
+
+| DPG Start Version |        DP A        |        DP B        |        DP C        | DPG End Version |
+|:-----------------:|:------------------:|:------------------:|:------------------:|:---------------:|
+|       1.0.0       |       1.0.0        | 1.3.1 → 1.3.2 |         -          |      1.0.1      |
+|       1.0.1       | 1.0.0 → 1.1.0 |       1.3.2        |         -          |      1.1.0      |
+|       1.1.0       |       1.1.0        |     (removed)      |       1.0.0        |      2.0.0      |
+|       2.0.0       |       1.1.0        |         -          | 1.0.0 → 2.0.0 |      3.0.0      |
+
+In row 1, DP B undergoes a patch version increment, which triggers a patch version increment for the DPG.
+In row 2, DP A undergoes a minor version increment, which triggers a minor version increment for the DPG.
+In row 3, DP B is replaced by DP C, which triggers a major version increment for the DPG.
+In row 4, DP C undergoes a major version increment, which triggers a major version increment for the DPG.
+
+### Consequences
+
+- Maintaining version numbers for decision point groups will add a small burden to each decision point group.
+- Semantic versioning will make it easier to track changes to decision point groups over time.
+- Because we don't anticipate frequent changes to decision point groups, the burden of maintaining version numbers should be minimal.
+- We are deliberately avoiding using the _name_ of the Decision Point Group as part of the versioning scheme, as
+in the motivating example in
+[ADR 0004](/0004-ssvc-decision-point-groups-are-versioned.md) we shifted the
+group name from _Patch Applier_ to _Deployer_, but since the group is still
+intended to represent the same _stakeholder role_ and _decision_, we want
+to be able to treat name changes as aliases rather than versioning events.
+
+## More Information
+
+- [Github Discussion #303](https://github.com/CERTCC/SSVC/discussions/303)

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/)

docs/adr/index.md

@@ -7,7 +7,8 @@
 * [0001 - Use Markdown Architectural Decision Records](0001-use-markdown-architectural-decision-records.md)
 * [0002 - SSVC Decision Points are versioned using Semantic Versioning](0002-ssvc-decision-points-are-versioned.md)
 * [0003 - SSVC Decision Points Versioning Rules](0003-ssvc-decision-point-versioning-rules.md)
-* 
+* [0004 - SSVC Decision Point Groups are Versioned using SemVer](0004-ssvc-decision-point-groups-are-versioned.md)
+* [0005 - SSVC Decision Point Group Versioning Rules](0005-ssvc-decision-point-group-versioning.md)
 
 ## Rejected Records