Skip to content

Commit 8f511e7

Browse files
feat: Rewrite 'Compatibility and Migration' in RFD template
Based on conversations with Matt Power, I've amended the text of the "Compatibility and Migration" section of the RFD template in a couple of ways: 1. Removed explicit reference to SchemaVer as the versioning scheme of choice for the CVE Record Format. 2. Introduced a set of questions which must specifically be answered in any submitted RFD. The key goal here is to balance the need for a high level of rigor around compatibility and migration in CVE because it is a systemically-important and large multi-stakeholder system with the need to not be overly prescriptive in the RFD template in ways which may in fact reduce rigor by over-specializing RFD requirements on today's considerations for what the important questions are. The questions included are specific, and intended to capture key concerns about forward compatibility and the impact of changes on CVE consumers particularly. Separately, references to SchemaVer were removed because, while it is my understanding that SchemaVer is the version scheme of choice for the CVE Record Format, that is not currently codified and itself likely ought to go through an RFD process to firmly resolve. In fact, Matt Power has raised concerns that SchemaVer may be insufficiently expressive for the versioning constraints under which CVE operates, and I'd rather not attempt to resolve that question in the context of this process-focused RFD. Signed-off-by: Andrew Lilley Brinker <abrinker@mitre.org>
1 parent 9579891 commit 8f511e7

1 file changed

Lines changed: 40 additions & 37 deletions

File tree

rfds/_TEMPLATE.md

Lines changed: 40 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -70,43 +70,46 @@ expectations to CVE stakeholders.
7070
## Compatibility and Migration
7171
[compatibility-and-migration]: #compatibility-and-migration
7272

73-
Describe the SchemaVer compatibility between the current development version of
74-
the record format and the changes proposed in the RFD.
75-
76-
SchemaVer defines three levels of compatibility, delineated as a version triple
77-
of the form `MODEL-REVISION-ADDITION`:
78-
79-
- `MODEL`: Incremented for breaking changes which present interaction with
80-
_any_ historic data.
81-
- `REVISION`: Incremented for changes which prevent interaction with _some_
82-
historic data.
83-
- `ADDITION`: Incremented for changes which _do not_ prevent interaction with
84-
_any_ historic data.
85-
86-
Also describe any migration paths required of CVE stakeholders, including any
87-
requirement to transition from a prior structure in the schema to a new
88-
structure, or to comply with stricter data quality constraints.
89-
90-
Some of the following questions may be important to answer, depending on the
91-
scale of the changes proposed in an RFD:
92-
93-
- How long should the proposed change be communicated to CVE stakeholders in
94-
advance of being rolled out in CVE Services?
95-
- What types of testing are necessary before the change is rolled out into
96-
production? (This testing may also be part of the Success Metrics and
97-
rollback criteria.)
98-
99-
While SchemaVer's compatibility rules only consider the impact of a change on
100-
the ability of users of a schema to interact with _historic_ data, any change
101-
to the schema which adds new capabilities places a demand on CVE stakeholders
102-
to adapt. For CNAs and ADPs this may mean updating their integrations with
103-
CVE Services to provide data in new fields, while for CVE consumers it may
104-
require amending their CVE record parsing to make use of new data or be able to
105-
parse new records.
106-
107-
This fact, that `ADDITION`-level changes still create work for CVE stakeholders,
108-
should never be used as a sole reason to reject a proposed RFD, but it should
109-
strongly inform any roll out plan for changes.
73+
Describe the impacts of the proposed change on both backward and forward
74+
compatibility.
75+
76+
To address backward compatibility, explain if and how your proposal would
77+
impact users of the schema's ability to parse existing CVE records produced
78+
under prior versions of the CVE Record Format.
79+
80+
To address forward compatibility, explain if current users of the schema would
81+
be able to accept all, some, or none of the records produced with the schema as
82+
modified by your proposal.
83+
84+
These explanations must specifically answer the following questions:
85+
86+
1. Does your proposal modify an `enum` type to add, remove, or modify the set
87+
of acceptable values?
88+
2. Does your proposal modify a closed set of required fields to add a new
89+
required field or a new alternative set of required fields?
90+
3. Does your proposal involve the addition of a new format which CVE consumers
91+
would need to parse? If it does include a new format...
92+
1. How complex is the format to parse?
93+
2. Are there parser implementations available under open source licenses,
94+
and for what programming languages?
95+
96+
You must also address considerations for planning migration of CVE stakeholders
97+
to support your proposed changes. This includes both the impacts to CVE
98+
producers, including CVE Numbering Authorities (CNAs) and Authorized Data
99+
Publishers (ADPs), and impacts to CVE consumers.
100+
101+
Considerations for migration, which must be addressed in your explanation,
102+
include:
103+
104+
1. How long should the proposed change be communicated to CVE stakeholders
105+
before being implemented in production?
106+
2. What testing would be needed before the change is implemented in production?
107+
108+
As CVE is a large and multi-stakeholder system, detail and sensitivity in this
109+
section of an RFD are extremely important. Particular scrutiny should be paid
110+
by both RFD submitters and reviewers to understand the impacts of any proposed
111+
change on all sides of the CVE system, including producers (CNAs, ADPs),
112+
consumers, the CVE Board and Working Groups, and the Secretariat.
110113

111114
## Success Metrics
112115
[success-metrics]: #success-metrics

0 commit comments

Comments
 (0)