From 7de8fbb4389dc4bdc9699127097bb9f6aa61acd0 Mon Sep 17 00:00:00 2001 From: Andrew Lilley Brinker Date: Tue, 29 Apr 2025 09:41:16 -0700 Subject: [PATCH 1/7] feat: Introduce an RFD process. This introduces a new Request for Discussion (RFD) process for considering changes to the CVE Record Format. The details of the proposal are in the commit. This commit includes both the first RFD, proposing the introduction an RFD process and modeling what the process looks like, as well as a template for future RFDs to reuse. Signed-off-by: Andrew Lilley Brinker --- rfds/0000-establishing-the-rfd-process.md | 440 ++++++++++++++++++++++ rfds/_TEMPLATE.md | 155 ++++++++ 2 files changed, 595 insertions(+) create mode 100644 rfds/0000-establishing-the-rfd-process.md create mode 100644 rfds/_TEMPLATE.md diff --git a/rfds/0000-establishing-the-rfd-process.md b/rfds/0000-establishing-the-rfd-process.md new file mode 100644 index 00000000000..70ea0389ffd --- /dev/null +++ b/rfds/0000-establishing-the-rfd-process.md @@ -0,0 +1,440 @@ +# Establishing the RFD Process + +| Field | Value | +|:-----------------|:----------------------| +| RFD Submitter | Andrew Lilley Brinker | +| RFD Pull Request | [RFD #0000](https://github.com/CVEProject/cve-schema/pull/405) | + +## Summary +[summary]: #summary + +Introduce a Request for Discussion (RFD) process to manage changes to the +CVE Record Format. The goals of this process are to make proposals clearer and +easier for the [Quality Working Group][qwg] to assess, to provide a clear focal +point for community engagement with proposed changes, to increase the rigor of +the process for evolving the record format, and to provide a historic record of +prior proposals to help inform future work on the record format. + +## Problem Statement +[problem-statement]: #problem-statement + +Today, the process for evolving the CVE Record Format is often informal and +difficult to track, both as a participant in the CVE +[Quality Working Group][qwg] and for outside observers. + +This is true for several reasons. First, work within the QWG spans both a +private venue open to CVE Program participants and invited individuals (QWG +meetings and the QWG mailing list) and a public venue in which anyone may +comment (the [CVEProject/cve-schema][gh_repo] repository on GitHub). While the +QWG is generally welcoming to individuals who request admission and aren't [CVE +Program participants][qwg_members], this requirement to request admission does +create a barrier to participation that increases the friction of engaging with +CVE Project stakeholders. + +This dual-venue challenge also means that materials for proposals may be spread +across different venues: they may be shared directly with QWG members privately +via meetings and the QWG mailing list, or they may be found in Issues, +Discussions, and Pull Requests on the [cve-schema GitHub repository][gh_repo]. +While _eventually_ all proposals to amend the CVE Record Format must +materialize as Pull Requests on GitHub, this may procedurally occur after +de-facto approval via consensus by the QWG or a vote by the +[CVE Board][cve_board]. + +When proposals exist only within the QWG, they may be tracked informally in +ways which make it difficult to follow the status of proposals, both in terms +of whether they've been advanced by the QWG to the CVE Board for a vote, and +in terms of whether they've addressed all submitted concerns during the QWG's +process of deliberation. Given that the QWG is governed by consensus, in the +style of the [IETF's "lack of disagreement" / humming standard][ietf_humming], +difficulty tracking the status of open items of disagrement becomes a +meaningful barrier to progress of items out of the QWG and up to the CVE Board +for a vote. + +What's more, this messiness also makes it difficult to reconstruct a historical +record of what proposals have been considered, what trade-offs or alternatives +were part of that consideration, or even what may have motivated a prior +change. This kind of record of deliberation can be invaluable for future +efforts to review, reconsider, or expand upon prior decisions. + +In summary, the central goal of this proposal to introduce an RFD process is to +make the process of amending the CVE Record Format more [_legible_][slas], both +to members of the Quality Working Group and to outside participants. + +For QWG members, an RFD proposal can collect open questions which have not yet +been resolved by consensus, and identify use cases, goals, and other +considerations underlying proposals. The discussion around an RFD's Pull +Request can also become a focal point for collecting such feedback in advance +of actual implementation, helping to centralize any digital discussions and +thus make the process of participating in the QWG smoother and less +time-consuming. + +For outside participants, an RFD provides a convening place for feedback and +input which can happen contemporaneously with the QWG's own deliberation. By +commenting on an RFD, an outside contributor can be sure they are providing +timely input on a proposal which is still under active consideration, and can +have a better view into the reasoning which may be behind such a proposal. +This should help to make the process of gathering and organizing community +feedback easier on both sides. + +Tracking RFDs would also become a way for engaged consumers of CVE records to +stay informed about upcoming changes before they land in the CVE Services +[live testing environment][cve_test_env] or are rolled out to production users. + +## Proposed Solution +[proposed-solution]: #proposed-solution + +We propose introducing a "Request for Discussion" (RFD) process, modeled after +similar processes such as: + +- [The Oxide Computer Company's RFD process.][rfds_oxide] +- [The Python PEP process.][pep_python] +- [The OpenJDK JEP process.][jep_openjdk] +- [The Rust RFC process.][rfc_rust] + +Broadly, an RFD process is a process by which proposals for a project are made +in the form of detailed documents, which are submitted by an initial submitter, +workshopped via feedback by project stakeholders, and then eventually accepted +or rejected. Accepted RFDs are then tracked in a formal tracking system, +forming a written historic record of proposed and implemented changes for the +project. + +In our case, we propose adopting an RFD process to manage proposals to amend +the CVE Record Format. The remainder of this section will try to answer key +questions about this process, including: + +- Who can submit an RFD? +- What should require an RFD? +- How are RFDs submitted? +- What process would RFDs follow after submission? +- What happens to rejected RFDs? +- What happens to accepted RFDs? + +### Who can submit an RFD? + +RFDs may be submitted by participants in the [CVE Quality Working Group][qwg]. + +The QWG is open for participation by [CVE Project participants][qwg_members], +including: + +- Members of the CVE Board +- Representatives of CVE Numbering Authorities +- Representatives of Authorized Data Publishers +- Participants from the CVE Secretariat (currently The MITRE Corporation) + +On a case-by-case basis, the QWG can invite to participate, through consensus, +individuals who are not CVE program members. To request admission to the QWG, +please contact one of the QWG Co-Chairs. + +Individuals wishing to submit an RFD who are not QWG participants should first +request admittance to participate prior to submitting the RFD, so that they +can be present for direct synchronous discussions about their proposal. If the +scheduled time for synchronous QWG meetings is not workable for an RFD +proposer then alternative QWG meeting times or special briefings to inform the +QWG members may be discussed and approved by the QWG. + +RFDs submitted by individuals who are not QWG participants and have not +requested participation in the QWG will be responded to with a prompt to +participate in the QWG. If the submitter does not respond in a timely manner or +declines to engage with the QWG, then the RFD will be closed and rejected, +though the rejection will not preclude future consideration of the merits of +the contents of the RFD if proposed at a future time consistent with the +requirements of the RFD process. + +### What Should Require an RFD? + +Changes to the CVE Record Format of the following types will require an +approved RFD prior to implementation: + +1. Adding, modifying, or removing fields +2. Adding, modifying, or removing data constraints + +Changes to the format that do not do either of the above do not require an +RFD, although RFDs could still be submitted to aid in discussion and tracking +of a proposal. Other kinds of changes might include updating or adding +descriptions to fields, or adding or modifying field examples. + +In general, if you are in doubt about whether a proposal should start with an +RFD, ask the Quality Working Group. + +### How are RFDs submitted? + +RFDs should be submitted as Pull Requests against the [CVEProject/cve-schema +Git repository on GitHub][gh_repo], made against the +[`develop`][gh_repo_develop] branch. The precise steps for submitting a new +RFD are: + +- [Fork the CVEProject/cve-schema repository][gh_forking] to your own user + account. +- [Create a new branch for your RFD proposal][gh_branching], branching off of + the `develop` branch from CVEProject/cve-schema. +- In this new branch, copy the file `rfds/_TEMPLATE.md` from the root of your + checked out copy of your fork of CVEProject/cve-schema to a new file of the + form `rfds/0000-.md`, replacing `<TITLE>` with an [ASCII][ascii] title + for the RFD, with words separated by dashes. +- Complete the template as described within that copied document. The text in + each section of the template describes the substance of the material that + should be in that section. +- [Commit the changes][gh_commit] with a descriptive commit message describing + the proposal. +- [Open a pull request][gh_pr] from your feature branch to the `develop` branch on the + CVEProject/cve-schema repository. +- After the pull request is open, amend the RFD proposal file to link to that + Pull Request. Leave the RFD number as `0000`, it will be modified upon + acceptance (if accepted) to take the next available integer ID for an RFD. + Commit and push that modification to the RFD file. + +### What process would RFDs follow after submission? + +The Quality Working Group operates by [consensus][ietf_humming], with +discussions taking place during QWG meetings. Submitted RFDs may be placed on +the agenda for discussion at future QWG meetings, and may remain as part of the +ongoing agenda of the QWG until a determination is reached to either advance +the proposal to the CVE Board for a final approval or rejection, or to not +advance the proposal. + +Additionally, both QWG members and outside stakeholders should voice open +questions or points of disagreement in the pull request for the RFD. These open +points should be tracked in a comment maintained by a QWG Co-Chair or by the +RFD submitter. The presence of tracked unresolved points of disagreement should +be treated as a blocker for the QWG to proceed with advancing an RFD to the +CVE Board. + +Final approval of all proposals for the CVE Record Format must be done by the +CVE Board. While the QWG has the power to refuse to advance a proposal to the +Board if they do not consider it worthwhile to pursue, the Board makes the +decision to approve or reject a proposal after the QWG advances it to them. + +When the CVE Board votes on a proposal advanced by the QWG, the results of that +vote shall be added to the discussion on the relevant RFD Pull Request by a +QWG Co-Chair. + +There is no set schedule by which an RFD must be considered, either by the QWG +or by the CVE Board, nor is there a set schedule for QWG meetings. The specific +schedule for QWG may vary at the discretion of the QWG Co-Chairs. Contact the +Co-Chairs for information on the current QWG meeting schedule. + +If an RFD remains unresolved and inactive for a period of 3 months (inactive +meaning no new points of discussion have been raised on the RFD's pull request +and the RFD has not been part of the agenda for meetings of the QWG or the +CVE Board), it may be closed by a QWG Co-Chair as a rejection. In which case it +may be resubmitted in the future as is the case with all rejections. + +If the QWG makes a determination to advance an RFD to the CVE Board, a Co-Chair +must make a comment on the RFD Pull Request indicating it has been advanced to +the Board. If the Board votes on the RFD, the results of that vote must be +recorded to the RFD Pull Request by a QWG Co-Chair. + +### What happens to rejected RFDs? + +Rejected RFDs will have their Pull Requests closed, with a final comment from +a representative of the QWG (usually a QWG Chair) indicating the disposition +of the group and optionally providing feedback on the proposal. + +Rejected RFDs may be re-proposed in the future, with a new RFD document, if +they address issues raised in a prior submission sufficiently well. RFDs which +are re-proposals should refer to and link to the Pull Request for the prior +instance of the RFD to provide a clear historic record. + +### What happens to accepted RFDs? + +Accepted RFDs, meaning RFDs which have been advanced to the CVE Board by the +QWG and which the CVE Board has voted to approve, will be merged into the +[CVEProject/cve-schema][gh_repo] repository, and a Tracking Issue will then be +opened on the repository to track progress on implementing the changes proposed +in the RFD. The changes, as they've in-principle been approved by the CVE Board +as part of the process of approving the RFD, will not need to be re-reviewed by +the Board. + +When all implementation of the RFD is complete and has been merged, the +Tracking Issue will be closed and the changes proposed by the RFD and now +implemented subsequent to its merging will become part of the next release of +the CVE Record Format. + +If an RFD fails to pass its own self-defined success criteria within the +defined period, the changes described by the RFD will be rolled back. The +timeline for rollbacks will be coordinated between the QWG, the CVE Board, and +the AWG. Rollbacks do not require a new vote of the CVE Board or a re-review +by the QWG, except to coordinate the logistics of enacting a rollback and +communicating about it to CVE stakeholders. + +## Examples +[examples]: #examples + +This document itself, as the first RFD, is an example of the format of an RFD, +and of the process an RFD should follow for acceptance. + +As this RFD does not propose changes to the schema, this section does not +include any such example changes. In any RFD which does propose changes to the +CVE Record Format, examples should be provided in the "Examples" section, as +described in the RFD template. + +## Impact Assessment +[impact-assessment]: #impact-assessment + +The introduction of an RFD process comes with both benefits and costs. + +In terms of benefits, it helps to make the process of proposing and considering +changes to the CVE Record Format more rigorous, consistent, and transparent. +Members of the QWG can more easily track what proposals are currently open, and +what proposals have been approved but not yet implemented. For non-QWG +participants in the process, it becomes easier to identify when changes are +being discussed and to provide your independent perspective through engagement +in an RFD's Pull Request. + +RFD's also help to provide a historical record of prior accepted proposals, +including motivation and reasoning behind a proposal. This helps avoid future +"Chesterton's Fence" issues where no one involved in the QWG or the community +was present for the discussions around the introduction of a change in the +Record Format, and thus is unable to assess why such a change had been made. + +The inclusion of success metrics and a rollback mechanism within the RFD +process should also help to avoid situations where changes are made to the +format which turn out to be unnecessary and are not widely adopted by the +CVE ecosystem. Rather than new unused features becoming dead weight in the +specification, there can be a well-understood process for their removal. + +In terms of costs, the introduction of an RFD process makes proposing changes +to the CVE Record Format more time-consuming. Proposers now need to produce a +detailed written document capturing their proposal and the evidence for it +being worthwhile, which may be a barrier to new proposals. In practice this +may still be comparable to the current more ad-hoc process which often involves +the production of presentation slides, written documents, and code changes +which are submitted and shared across QWG meetings and public Pull Requests. + +RFDs also do not resolve dysfunction regarding divergence of values or goals +among the QWG or between CVE and its stakeholders. As the QWG operates by +consensus, an inability to reach consensus can, despite the RFD process, still +result in deadlock and an inability to proceed in making changes. + +## Compatibility and Migration +[compatibility-and-migration]: #compatibility-and-migration + +There are no compatibility or migration concerns for this RFD, as it concerns +the establishment of the RFD process itself, and does not contain any proposals +for amending the CVE Record Format. + +## Success Metrics +[success-metrics]: #success-metrics + +6 months after the acceptance and adoption of this RFD process, the QWG should +solicit a survey to QWG members and outside CVE stakeholders about the value +of the RFD process. The results of that survey will be scored and compared +against a threshold, and if the average results of the survey do not pass the +required minimum threshold to indicate worthwhile value from the process, then +the RFD process will be rolled back and will not be required for future +proposals. + +To limit the possibility of "gaming" the survey by choosing questions +after-the-fact which may unduly influence the outcome of the survey, the +questions to be used are included in this RFD proposal, and shall not be +changed when the survey is held. + +The initial questions on the survey will be used to determine whether answers +will be considered for scoring. Anyone who answers "false" to both of the +following questions will not have their answers considered for the purpose of +scoring the survey results to determine whether the RFD has succeeded at its +success metric: + +1. "I am a participant in the CVE Quality Working Group (have attended at least + one CVE QWG meeting in the past six months)" +2. "I am a CVE ecosystem stakeholder (have consumed CVE records in the past six + months)" + +All other question answers are given on a 5-level Likert scale, with each +answer being assigned a point value, as follows: + +- Strongly disagree (1 point) +- Disagree (2 points) +- Neither agree nor disagree (3 points) +- Agree (4 points) +- Strongly agree (5 points) + +The questions will be: + +3. "The CVE QWG's RFD process has made tracking the status of proposals to + amend the CVE Record Format easier." +4. "The CVE QWG's RFD process has improved the level of rigor applied to + proposals to amend the CVE Record Format." +5. "The CVE QWG's RFD process has made it easier to gather input on proposals + to amend the CVE record format from QWG members." +6. "The CVE QWG's RFD process has made it easier to gather input on proposals + to amend the CVE Record Format from outside stakeholders." + +To score the results, consider only answers from respondents who answered +"true" to at least one of the two qualification questions (questions 1 and 2). +Then add up the scores for all Likert scale questions from all qualifying +respondents. Add up the total scores for all qualifying respondents, and divide +them by the number of qualifying respondents. + +If the average total score is greater than 12, the success criteria has been +met, and the RFD will not be rolled back. + +If the average total score is less than or equal to 12, the success criteria +has not been met, and the RFD will be rolled back. + +12 is chosen as the threshold as it would be the total score for an all-neutral +set of responses from a single respondent. + +## Supporting Data or Research +[supporting-data-or-research]: #supporting-data-or-research + +RFD processes are well-attested within software communities. Some existing +RFD-equivalent processes are identified in the "Proposed Solution" section +above, and this is not an exhaustive list of such processes. + +In general, RFD processes are desirable in large, multi-stakeholder projects +where the threshold for enacting changes ought to be high because the impact +of any changes is broad, and where there is a broad set of stakeholders who +need to coordinate and be involved in deliberation around changes. + +The demand for this process comes from the QWG itself. QWG members have +expressed concern with a lack of rigor in the QWG's process for considering +proposals, including challenges with tracking the state of proposals, recording +evidence and success metrics, recalling key arguments for or against proposals, +and otherwise tracking and following the status of discussions around a +proposal. + +## Related Issues or Proposals +[related-issues-or-proposals]: #related-issues-or-proposals + +There are currently no alternative proposals open with the QWG to amend the +process of considering changes to the CVE Record Format. + +Alternate processes might be considered, but we do not present alternative +procedural designs here. + +## Recommended Priority +[recommended-priority]: #recommended-priority + +Medium + +## Unresolved Questions +[unresolved-questions]: #unresolved-questions + +None currently. + +## Future Possibilities +[future-possibilities]: #future-possibilities + +Future amendments to the RFD process itself may be warranted, or other +procedural changes to how the QWG operates. For example, clearer membership +rules and procedures, or a transition from a consensus to a voting-based +process for making recommendations to the CVE Board. + +[ascii]: https://developer.mozilla.org/en-US/docs/Glossary/ASCII +[cve_board]: https://www.cve.org/ProgramOrganization/Board +[cve_test_env]: https://www.cve.org/allresources/cveservices#TestEnvironment +[gh_branching]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository +[gh_commit]: https://github.com/git-guides/git-commit +[gh_forking]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo +[gh_pr]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request +[gh_repo]: https://github.com/CVEProject/cve-schema +[gh_repo_develop]: https://github.com/CVEProject/cve-schema/tree/develop +[ietf_humming]: https://datatracker.ietf.org/doc/html/rfc7282 +[jep_openjdk]: https://openjdk.org/jeps/1 +[qwg]: https://github.com/CVEProject/quality-workgroup +[qwg_members]: https://github.com/CVEProject/quality-workgroup?tab=readme-ov-file#2-working-group-membership +[pep_python]: https://peps.python.org/pep-0001/ +[rfc_rust]: https://github.com/rust-lang/rfcs/blob/master/text/0002-rfc-process.md +[rfds_oxide]: https://rfd.shared.oxide.computer/rfd/0001 +[slas]: https://en.wikipedia.org/wiki/Seeing_Like_a_State diff --git a/rfds/_TEMPLATE.md b/rfds/_TEMPLATE.md new file mode 100644 index 00000000000..e484973ed86 --- /dev/null +++ b/rfds/_TEMPLATE.md @@ -0,0 +1,155 @@ +# (Title) + +| Field | Value | +|:-----------------|:-------| +| RFD Submitter | (NAME) | +| RFD Pull Request | [RFD #0000](https://github.com/CVEProject/cve-schema/pull/1234) | + +## Summary +[summary]: #summary + +One paragraph explanation of the proposed schema change. + +## Problem Statement +[problem-statement]: #problem-statement + +Explain the motivation for the proposed change to the CVE Record Format, +including what problems it may solve for users of CVE, or what additional +capability it may provide. This should explain all necessary background in +detail, so it is understandable to someone without prior knowledge or +experience with the relevant problems. It should also make clear the severity +of the problem being described. + +The problem statement should describe who is affected by the problem, with +specific use cases where the proposed change would help users of CVE, whether +those users are CVE Numbering Authorities or Authorized Data Publishers +submitting data to CVE Services, or consumers of CVE data to forward to their +own customers or to manage their own security risks. + +This section should explicitly answer the question: "what happens if we do +nothing?" + +## Proposed Solution +[proposed-solution]: #proposed-solution + +Explain in detail the proposed change to the CVE Record Format, including +why those changes are made and how they will address the problems or provide +the capabilities described in the Problem Statement. This should be very +detailed, so as to make clear to reviewers exactly what is necessary to +implement the RFD if it is accepted. RFD proposal time is the time to identify +and resolve ambiguities and uncertainties in the actual schema changes +required for a proposal, as they provide the clearest opportunity for the +QWG members and community stakeholders to review and provide input on proposed +changes. + +If a change is to implemented in multiple parts or stages, those should be +delineated separately in the RFD document, to make clear what process would be +followed if it is accepted. + +## Examples +[examples]: #examples + +Provide examples of the relevant new or modified fields in the record format. +If an RFD is only proposing eliminating or deprecating existing fields, +examples should show what the relevant container objects would like after the +change, and how the reduced schema would continue to serve the needs and +interests of CVE users. + +Diagrams may also be included here to visualize the change in structure +proposed by an RFD. + +## Impact Assessment +[impact-assessment]: #impact-assessment + +Describe the benefits and possible risks associated with an RFD, including +the weaknening or strengthening of data quality constraints and any +requirements to enforce data quality rules via CVE Services application logic +(when not enforceable in the schema itself) or to communicate constraints or +expectations to CVE stakeholders. + +## Compatibility and Migration +[compatibility-and-migration]: #compatibility-and-migration + +Describe the SchemaVer compatibility between the current development version of +the record format and the changes proposed in the RFD. + +SchemaVer defines three levels of compatibility, delineated as a version triple +of the form `MODEL-REVISION-ADDITION`: + +- `MODEL`: Incremented for breaking changes which present interaction with + _any_ historic data. +- `REVISION`: Incremented for changes which prevent interaction with _some_ + historic data. +- `ADDITION`: Incremented for changes which _do not_ prevent interaction with + _any_ historic data. + +Also describe any migration paths required of CVE stakeholders, including any +requirement to transition from a prior structure in the schema to a new +structure, or to comply with stricter data quality constraints. + +## Success Metrics +[success-metrics]: #success-metrics + +Describe how success for an RFD will be determined, including expectations for +adoption of any new fields by CNAs or ADPs over a defined timeline. Also +describe any available options to assess adoption of new fields by CVE data +consumers, which may require engagement with known CVE consumer communities. + +Success metrics must include: + +- A fixed timeline for deciding success or failure. +- An unambiguous mechanism for determining success or failure. +- If the metric will involve qualitative assessment of success with CVE + stakeholders, for example via a survey or direct outreach, all questions for + this engagement must be pre-registered in the RFD. + +Describe a path to rollback RFD changes if the success metrics are not met +in the prescribed time. + +## Supporting Data or Research +[supporting-data-or-research]: #supporting-data-or-research + +Describe any evidence for the need to adopt the RFD proposal based on +community demand for specific new data or demand for better data quality. + +## Related Issues or Proposals +[related-issues-or-proposals]: #related-issues-or-proposals + +Identify other open proposals and alternative options which may be considered +by the QWG if the RFD is not deemed acceptable. Link to other proposals if +appropriate. + +## Recommended Priority +[recommended-priority]: #recommended-priority + +Identify a recommended priority for the proposal based on the RFD author's +assessment of the proposal's value and ecosystem demand. + +Possible values are: + +- __Low__: The RFD addresses minor inconsistencies or errors in the CVE Record + Format which ought to be fixed but which do not present a substantive problem + for CVE consumers. +- __Medium__: The RFD addresses a deficiency in the CVE Record Format which + limits the value CVE consumers get from CVE records. +- __High__: The RFD addresses a severe deficiency in the CVE Record Format + which is interfering with the ability of CVE consumers to manage risks from + vulnerabilities. + +## Unresolved Questions +[unresolved-questions]: #unresolved-questions + +Identify any unresolved questions related to the RFD. Ideally, all questions +listed in this section will be resolved during consideration of the RFD. +Questions which are deemed out of scope for an RFD should be moved to the +Future Possibilities section to make clear they remain open and can be the +subject of a future RFD. + +## Future Possibilities +[future-possibilities]: #future-possibilities + +Describe future extensions of the changes proposed in the RFD, including any +unresolved questions which the QWG may wish to resolve at a future date. If +an RFD is part of a larger strategy, identify the remaining steps in that +strategy to help contextualize the work of the RFD within the goals and values +of the QWG. From 1e810892b57bc6ac23db5295aa4dbdf86c014a87 Mon Sep 17 00:00:00 2001 From: Andrew Lilley Brinker <abrinker@mitre.org> Date: Thu, 22 May 2025 14:21:22 -0700 Subject: [PATCH 2/7] chore: Clarify RFD acceptance procedures This clarifies the procedures around updating the RFD number in an RFD pull request after approval of an RFD by the CVE Board. Signed-off-by: Andrew Lilley Brinker <abrinker@mitre.org> --- rfds/0000-establishing-the-rfd-process.md | 24 +++++++++++++++-------- 1 file changed, 16 insertions(+), 8 deletions(-) diff --git a/rfds/0000-establishing-the-rfd-process.md b/rfds/0000-establishing-the-rfd-process.md index 70ea0389ffd..0ac03274127 100644 --- a/rfds/0000-establishing-the-rfd-process.md +++ b/rfds/0000-establishing-the-rfd-process.md @@ -179,9 +179,9 @@ RFD are: - [Open a pull request][gh_pr] from your feature branch to the `develop` branch on the CVEProject/cve-schema repository. - After the pull request is open, amend the RFD proposal file to link to that - Pull Request. Leave the RFD number as `0000`, it will be modified upon - acceptance (if accepted) to take the next available integer ID for an RFD. - Commit and push that modification to the RFD file. + Pull Request. Leave the RFD number as `0000`. Commit and push that + modification to the RFD file. If the RFD is accepted, the RFD number will be + modified by a QWG Co-Chair to take the next available integer ID for an RFD. ### What process would RFDs follow after submission? @@ -239,11 +239,19 @@ instance of the RFD to provide a clear historic record. Accepted RFDs, meaning RFDs which have been advanced to the CVE Board by the QWG and which the CVE Board has voted to approve, will be merged into the -[CVEProject/cve-schema][gh_repo] repository, and a Tracking Issue will then be -opened on the repository to track progress on implementing the changes proposed -in the RFD. The changes, as they've in-principle been approved by the CVE Board -as part of the process of approving the RFD, will not need to be re-reviewed by -the Board. +[CVEProject/cve-schema][gh_repo] repository via the following procedure. + +Upon acceptance of an RFD, a QWG Co-Chair will add a commit to the RFD's +Pull Request branch, updating the RFD document's RFD number in both the +filename prefix and within the header text of the RFD itself to use the +next-available integer ID. For example, if the most-recently-merged RFD had +the number #0003, the next RFD to be merged would use the ID #0004. + +After this commit is added, the Pull Request for the RFD will be merged by a +QWG Co-Chair, and a Tracking Issue will then be opened on the repository to +track progress on implementing the changes proposed in the RFD. The changes, +as they've in-principle been approved by the CVE Board as part of the process +of approving the RFD, will not need to be re-reviewed by the Board. When all implementation of the RFD is complete and has been merged, the Tracking Issue will be closed and the changes proposed by the RFD and now From 95798916b8de7c01fd136f02e1c3711fd3b2d862 Mon Sep 17 00:00:00 2001 From: Andrew Lilley Brinker <abrinker@mitre.org> Date: Fri, 30 May 2025 08:15:05 -0700 Subject: [PATCH 3/7] feat: Expand migration requirements in template. At Matt Powers' recommendation, this amends the "Compatibility and Migration" section of the RFD template to describe expectations for analyzing and planning migrations more clearly, including specific questions which ought to be answered, and clarifying the limits of SchemaVer in expressing the adoption burden of new features. Signed-off-by: Andrew Lilley Brinker <abrinker@mitre.org> --- rfds/_TEMPLATE.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/rfds/_TEMPLATE.md b/rfds/_TEMPLATE.md index e484973ed86..fec220dda37 100644 --- a/rfds/_TEMPLATE.md +++ b/rfds/_TEMPLATE.md @@ -87,6 +87,27 @@ Also describe any migration paths required of CVE stakeholders, including any requirement to transition from a prior structure in the schema to a new structure, or to comply with stricter data quality constraints. +Some of the following questions may be important to answer, depending on the +scale of the changes proposed in an RFD: + +- How long should the proposed change be communicated to CVE stakeholders in + advance of being rolled out in CVE Services? +- What types of testing are necessary before the change is rolled out into + production? (This testing may also be part of the Success Metrics and + rollback criteria.) + +While SchemaVer's compatibility rules only consider the impact of a change on +the ability of users of a schema to interact with _historic_ data, any change +to the schema which adds new capabilities places a demand on CVE stakeholders +to adapt. For CNAs and ADPs this may mean updating their integrations with +CVE Services to provide data in new fields, while for CVE consumers it may +require amending their CVE record parsing to make use of new data or be able to +parse new records. + +This fact, that `ADDITION`-level changes still create work for CVE stakeholders, +should never be used as a sole reason to reject a proposed RFD, but it should +strongly inform any roll out plan for changes. + ## Success Metrics [success-metrics]: #success-metrics From 8f511e77507e401f4ba11fb82edec157665e4863 Mon Sep 17 00:00:00 2001 From: Andrew Lilley Brinker <abrinker@mitre.org> Date: Thu, 5 Jun 2025 10:15:37 -0700 Subject: [PATCH 4/7] 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> --- rfds/_TEMPLATE.md | 77 ++++++++++++++++++++++++----------------------- 1 file changed, 40 insertions(+), 37 deletions(-) diff --git a/rfds/_TEMPLATE.md b/rfds/_TEMPLATE.md index fec220dda37..e699a774817 100644 --- a/rfds/_TEMPLATE.md +++ b/rfds/_TEMPLATE.md @@ -70,43 +70,46 @@ expectations to CVE stakeholders. ## Compatibility and Migration [compatibility-and-migration]: #compatibility-and-migration -Describe the SchemaVer compatibility between the current development version of -the record format and the changes proposed in the RFD. - -SchemaVer defines three levels of compatibility, delineated as a version triple -of the form `MODEL-REVISION-ADDITION`: - -- `MODEL`: Incremented for breaking changes which present interaction with - _any_ historic data. -- `REVISION`: Incremented for changes which prevent interaction with _some_ - historic data. -- `ADDITION`: Incremented for changes which _do not_ prevent interaction with - _any_ historic data. - -Also describe any migration paths required of CVE stakeholders, including any -requirement to transition from a prior structure in the schema to a new -structure, or to comply with stricter data quality constraints. - -Some of the following questions may be important to answer, depending on the -scale of the changes proposed in an RFD: - -- How long should the proposed change be communicated to CVE stakeholders in - advance of being rolled out in CVE Services? -- What types of testing are necessary before the change is rolled out into - production? (This testing may also be part of the Success Metrics and - rollback criteria.) - -While SchemaVer's compatibility rules only consider the impact of a change on -the ability of users of a schema to interact with _historic_ data, any change -to the schema which adds new capabilities places a demand on CVE stakeholders -to adapt. For CNAs and ADPs this may mean updating their integrations with -CVE Services to provide data in new fields, while for CVE consumers it may -require amending their CVE record parsing to make use of new data or be able to -parse new records. - -This fact, that `ADDITION`-level changes still create work for CVE stakeholders, -should never be used as a sole reason to reject a proposed RFD, but it should -strongly inform any roll out plan for changes. +Describe the impacts of the proposed change on both backward and forward +compatibility. + +To address backward compatibility, explain if and how your proposal would +impact users of the schema's ability to parse existing CVE records produced +under prior versions of the CVE Record Format. + +To address forward compatibility, explain if current users of the schema would +be able to accept all, some, or none of the records produced with the schema as +modified by your proposal. + +These explanations must specifically answer the following questions: + +1. Does your proposal modify an `enum` type to add, remove, or modify the set + of acceptable values? +2. Does your proposal modify a closed set of required fields to add a new + required field or a new alternative set of required fields? +3. Does your proposal involve the addition of a new format which CVE consumers + would need to parse? If it does include a new format... + 1. How complex is the format to parse? + 2. Are there parser implementations available under open source licenses, + and for what programming languages? + +You must also address considerations for planning migration of CVE stakeholders +to support your proposed changes. This includes both the impacts to CVE +producers, including CVE Numbering Authorities (CNAs) and Authorized Data +Publishers (ADPs), and impacts to CVE consumers. + +Considerations for migration, which must be addressed in your explanation, +include: + +1. How long should the proposed change be communicated to CVE stakeholders + before being implemented in production? +2. What testing would be needed before the change is implemented in production? + +As CVE is a large and multi-stakeholder system, detail and sensitivity in this +section of an RFD are extremely important. Particular scrutiny should be paid +by both RFD submitters and reviewers to understand the impacts of any proposed +change on all sides of the CVE system, including producers (CNAs, ADPs), +consumers, the CVE Board and Working Groups, and the Secretariat. ## Success Metrics [success-metrics]: #success-metrics From d72c5ec2586b70a753aabcd6220c72d2be481e08 Mon Sep 17 00:00:00 2001 From: Andrew Lilley Brinker <abrinker@mitre.org> Date: Wed, 11 Jun 2025 11:07:40 -0700 Subject: [PATCH 5/7] chore: Update back-compact / forward-compat defs Amend the definitions of "backward compatibility" and "forward compatibility" in the "Compatibility and Migration" section of the RFD template to more clearly explain requirements for RFD writers. In the future we'd like this section to be more rigorous, and ideally to provide a detailed breakdown of what kinds of changes in the schema are considered "breaking," but the versioning rules for the CVE Record Format aren't sufficiently defined yet. I recommend developing an RFD to solidify the versioning rules, and then amending the template to require greater rigor around compatibility in this section. Signed-off-by: Andrew Lilley Brinker <abrinker@mitre.org> --- rfds/_TEMPLATE.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/rfds/_TEMPLATE.md b/rfds/_TEMPLATE.md index e699a774817..d015f4cd6bd 100644 --- a/rfds/_TEMPLATE.md +++ b/rfds/_TEMPLATE.md @@ -75,11 +75,16 @@ compatibility. To address backward compatibility, explain if and how your proposal would impact users of the schema's ability to parse existing CVE records produced -under prior versions of the CVE Record Format. +under prior versions of the CVE Record Format. Note that CVE records returned +by CVE Services are automatically updated to use new schema versions, so +interaction with historic CVE records would only arise for records stored and +obtained outside of CVE Services. To address forward compatibility, explain if current users of the schema would -be able to accept all, some, or none of the records produced with the schema as -modified by your proposal. +be able to parse all, some, or none of the records produced with the schema as +modified by your proposal. If CVE consumers would need to amend their existing +parsers for CVE records be able to parse records produced under the new schema, +describe what amendments would be necessary for them. These explanations must specifically answer the following questions: From 9c9aae34b9125852dde5477595faba591ab995cc Mon Sep 17 00:00:00 2001 From: Andrew Lilley Brinker <alilleybrinker@gmail.com> Date: Mon, 16 Jun 2025 17:05:51 -0700 Subject: [PATCH 6/7] Update rfds/_TEMPLATE.md Co-authored-by: Jon <darakian@github.com> --- rfds/_TEMPLATE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rfds/_TEMPLATE.md b/rfds/_TEMPLATE.md index d015f4cd6bd..22c7c3bf5a5 100644 --- a/rfds/_TEMPLATE.md +++ b/rfds/_TEMPLATE.md @@ -83,7 +83,7 @@ obtained outside of CVE Services. To address forward compatibility, explain if current users of the schema would be able to parse all, some, or none of the records produced with the schema as modified by your proposal. If CVE consumers would need to amend their existing -parsers for CVE records be able to parse records produced under the new schema, +parsers for CVE records to be able to parse records produced under the new schema, describe what amendments would be necessary for them. These explanations must specifically answer the following questions: From 5366f19fa67aa5157872199058bb479c3fbaed62 Mon Sep 17 00:00:00 2001 From: Andrew Lilley Brinker <abrinker@mitre.org> Date: Thu, 3 Jul 2025 14:07:15 -0700 Subject: [PATCH 7/7] chore: Use RFD #0001 for "Establishing the RFD Process" Per the RFD rules, assign ID #0001 to the first RFD. Signed-off-by: Andrew Lilley Brinker <abrinker@mitre.org> --- ...-the-rfd-process.md => 0001-establishing-the-rfd-process.md} | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename rfds/{0000-establishing-the-rfd-process.md => 0001-establishing-the-rfd-process.md} (99%) diff --git a/rfds/0000-establishing-the-rfd-process.md b/rfds/0001-establishing-the-rfd-process.md similarity index 99% rename from rfds/0000-establishing-the-rfd-process.md rename to rfds/0001-establishing-the-rfd-process.md index 0ac03274127..151e5e41529 100644 --- a/rfds/0000-establishing-the-rfd-process.md +++ b/rfds/0001-establishing-the-rfd-process.md @@ -3,7 +3,7 @@ | Field | Value | |:-----------------|:----------------------| | RFD Submitter | Andrew Lilley Brinker | -| RFD Pull Request | [RFD #0000](https://github.com/CVEProject/cve-schema/pull/405) | +| RFD Pull Request | [RFD #0001](https://github.com/CVEProject/cve-schema/blob/main/rfds/0001-establishing-the-rfd-process.md) | ## Summary [summary]: #summary