diff --git a/docs/adr/0003-ssvc-decision-point-versioning-rules.md b/docs/adr/0003-ssvc-decision-point-versioning-rules.md index c86faec3..b625d4cc 100644 --- a/docs/adr/0003-ssvc-decision-point-versioning-rules.md +++ b/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 --- diff --git a/docs/adr/0006-ssvc-decision-point-versioning-rules.md b/docs/adr/0006-ssvc-decision-point-versioning-rules.md new file mode 100644 index 00000000..580b4ae0 --- /dev/null +++ b/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/)