Modifying Decision Point Values

• Scenario: You need to modify a decision point value.
• Tricky part: We are versioning decision points, so any change to a value is a potential versioning event

Solution

• Do not modify the existing decision point value.
• Instead, copy it to a new value (giving it a new variable name in the process), then modify the copy
• Once the new decision point value has been created:
  • copy the existing decision point object to a new decision point object
  • revise the decision point object's values to include the new value instead of the old one
  • add the new decision point to the versions list in main()
  • run the module to see what it suggests with respect to version numbers (major, minor, patch)
  • decide what version number to increment and modify the decision point version string accordingly
• commit, push, PR etc.

Example

Consider the following Decision Point, having two values, "Yes" and "No".

YES = SsvcDecisionPointValue(
    name="Yes",
    key="Y",
    description="A public report of the vulnerability exists.",
)

NO = SsvcDecisionPointValue(
    name="No",
    key="N",
    description="No public report of the vulnerability exists.",
)

REPORT_PUBLIC_1 = SsvcDecisionPoint(
    name="Report Public",
    description="Is a viable report of the details of the vulnerability already publicly available?",
    key="RP",
    version="1.0.0",
    values=(
        NO,
        YES,
    ),
)

Imagine our task is that we need to modify the description that goes along with "No".

We copy the existing NO and modify the copy:

NO = SsvcDecisionPointValue(
    name="No",
    key="N",
    description="No public report of the vulnerability exists.",
)

NO_2 = SsvcDecisionPointValue(
    name="No",
    key="N",
    description="No public report (e.g., media coverage, blog posts, public mail list archives, git commits mentioning the vulnerability) of the vulnerability exists.",
)

Ignore for the moment that ADR-0007 says we prefer not to include examples in descriptions. This example is for illustrative purposes only.

Next, we need to make a copy of the Decision Point and modify the copy.

REPORT_PUBLIC_1 = SsvcDecisionPoint(
    name="Report Public",
    description="Is a viable report of the details of the vulnerability already publicly available?",
    key="RP",
    version="1.0.0",
    values=(
        NO,
        YES,
    ),
)

REPORT_PUBLIC_2 = SsvcDecisionPoint(
    name="Report Public",
    description="Is a viable report of the details of the vulnerability already publicly available?",
    key="RP",
    version="2.0.0",
    values=(
        NO_2,
        YES,
    ),
)

Note: The version="2.0.0", line is just a placeholder, we're going to need to adjust it in a moment.

Confirm version increments

We add the new version to the versions in main():

def main():
    versions = (REPORT_PUBLIC_1, REPORT_PUBLIC_2)
    print_versions_and_diffs(versions)

and run it to find:

Report Public v2.0.0 description did not change
Report Public v2.0.0 key did not change
Report Public v2.0.0 version changed from 1.0.0
Report Public v2.0.0 value names did not change
Report Public v2.0.0 value No key did not change
Report Public v2.0.0 value Yes key did not change
(patch) Report Public v2.0.0 value No description changed
Report Public v2.0.0 value Yes description did not change
Report Public v2.0.0 appears to be a patch change

So now we see that since only the one value description changed, we only need to increment the patch number. Let's fix that now.

In the variable name:

- REPORT_PUBLIC_2 = SsvcDecisionPoint(
+ REPORT_PUBLIC_1_0_1 = SsvcDecisionPoint(

In the version string:

-    version="2.0.0",
+    version="1.0.1",

and in the versions tuple in main():

-    versions = (REPORT_PUBLIC_1, REPORT_PUBLIC_2)
+    versions = (REPORT_PUBLIC_1, REPORT_PUBLIC_1_0_1)

And running the module once more just to check:

Report Public v1.0.1 description did not change
Report Public v1.0.1 key did not change
Report Public v1.0.1 version changed from 1.0.0
Report Public v1.0.1 value names did not change
Report Public v1.0.1 value Yes key did not change
Report Public v1.0.1 value No key did not change
Report Public v1.0.1 value Yes description did not change
(patch) Report Public v1.0.1 value No description changed
Report Public v1.0.1 appears to be a patch change

All done

And with that, it looks like we're good to go.

Commit, push, and PR away!