From 712df323f7b3ef2fd60b50e1617ff88fb9564d34 Mon Sep 17 00:00:00 2001 From: Alexey Kukanov Date: Wed, 18 Dec 2024 17:24:29 +0100 Subject: [PATCH] RFC process clarification (#1971) --- rfcs/README.md | 24 ++++++++++++++++++------ rfcs/experimental/README.md | 16 +++++++++------- rfcs/proposed/README.md | 4 +++- rfcs/supported/README.md | 3 ++- rfcs/template.md | 17 +++++++++++------ 5 files changed, 43 insertions(+), 21 deletions(-) diff --git a/rfcs/README.md b/rfcs/README.md index c56ed6cb04b..1c42f9ed8f3 100644 --- a/rfcs/README.md +++ b/rfcs/README.md @@ -66,14 +66,15 @@ The "RFC" label can be used to mark PRs containing RFC/design proposals. The RFC approval process generally follows the guidelines in the [UXL Foundation Operational Procedures]( https://github.com/uxlfoundation/uxl_operational_procedures/blob/release/Process_Documents/Organization_Operational_Process.md#review--approval-process). -Once two or more maintainers approve the PR, it is merged into the main branch -as an RFC proposed for implementation. +Once two or more maintainers approve the PR, it is merged into the main branch. -As the RFC moves to different states, use new PRs to update the RFC document -with additional information. +RFC documents can be developed iteratively at each stage. For example, an initial RFC +can be approved even if some details of the design or the API are not yet sufficiently +elaborated. In that case, subsequent revisions (new PRs) should update the document +in `rfcs/proposed`, adding the requested information. A proposal that is subsequently implemented and released as an experimental feature -is moved into the `rfcs/experimental` folder. +is moved into the `rfcs/experimental` directory. The RFC for such a feature should include a description of what is required to move it from experimental to fully supported -- for example, feedback from users, demonstrated performance improvements, etc. @@ -84,9 +85,20 @@ changes and should therefore have a link to the section in the specification with its formal wording. A feature that is removed or a proposal that is abandoned or rejected will -be moved to the `rfcs/archived` folder. It should state the reasons for +be moved to the `rfcs/archived` directory. It should state the reasons for rejection or removal. +There is no requirement that an RFC should pass all the stages in order. +A typical flow for an RFC would include at least `proposed` and `supported`; +however, any state can be skipped, depending on the progress and the needs. + +For a document that describes a wide set of functionality or a general direction +and includes sub-RFCs for specific features, a few instances might simultaneously +reside in different states, adjusted as necessary to reflect the overall progress +on the direction and on its sub-proposals. + +See the README files in respective directories for additional information. + ## Document Style Recommendations - Follow the document structure described in [template.md](template.md). diff --git a/rfcs/experimental/README.md b/rfcs/experimental/README.md index bd5b010d593..2f88751be86 100644 --- a/rfcs/experimental/README.md +++ b/rfcs/experimental/README.md @@ -5,19 +5,21 @@ released as experimental features in the library. An experimental feature is expected to have an implementation that is of comparable quality to a fully supported feature. Sufficient tests are required. -An experimental feature does not yet appear as part of the oneDPL +An experimental feature does not yet appear as part of the oneDPL specification. Therefore, the interface and design can change. There is no commitment to backward compatibility for experimental features. The documents in this directory should include a list of the exit conditions that need to be met to move the functionality from experimental to fully supported. -These conditions might include demonstrated performance improvements, -demonstrated interest from the community, -acceptance of the required specification changes, etc. +These conditions might include demonstrated performance improvements, demonstrated +interest from the community, acceptance of the required specification changes, etc. -For features that require specification changes, the document might -include wording for those changes or a link to any PRs opened -against the specification. +A document here needs to be updated if the corresponding feature undergoes +modifications while remaining experimental. Other changes, such as updates on the +exit conditions or on the implementation and usage experience, are also welcome. + +For features that require specification changes prior to production, the document might +include wording for those changes or a link to any PRs opened against the specification. Proposals in the `rfcs/experimental` directory do not remain there indefinitely. They should move either to `rfcs/supported` when they become fully supported diff --git a/rfcs/proposed/README.md b/rfcs/proposed/README.md index 9a848ad6eb4..2848b7ddb27 100644 --- a/rfcs/proposed/README.md +++ b/rfcs/proposed/README.md @@ -6,4 +6,6 @@ However, the proposed changes have not yet been implemented as a preview or fully supported feature of the library. RFCs in the `rfcs/proposed` directory should explain the motivation, -design, and open questions related to the proposed extension. +design, and open questions related to the proposed extension. There can be +several update iterations on a proposed RFC to clarify the necessary details +and address the questions before it is accepted for the implementation. diff --git a/rfcs/supported/README.md b/rfcs/supported/README.md index b193c62a2c1..8b313edc20a 100644 --- a/rfcs/supported/README.md +++ b/rfcs/supported/README.md @@ -9,4 +9,5 @@ changes in the oneDPL specification. The RFC document should, in that case, have a link to the formal wording in the specification. Proposals that appear in `rfcs/supported` may be retained indefinitely to -provide insight into the design of existing features. +provide insight into the design of existing features. They could be updated +over time if the corresponding functionality is extended or modified. diff --git a/rfcs/template.md b/rfcs/template.md index db229ed70c1..404b022ba01 100644 --- a/rfcs/template.md +++ b/rfcs/template.md @@ -16,14 +16,17 @@ discussions, etc. ## Proposal -Replace the text in this section with a full and detailed description of the proposal -with highlighted consequences. +Replace the text in this section with a detailed description of the proposal +with highlighted consequences. The description can be iteratively clarified +as the proposal matures. -Depending on the kind of the proposal, the description should cover: +Depending on the kind of the proposal, the description may need to cover the following: - New use cases supported by the extension. - The expected performance benefit for a modification, supported with the data, if available. - The API of extensions such as class definitions and function declarations. +- Key technical design aspects, sufficient to understand how the functionality should work + and produce the desired outcome. A proposal should clearly outline the alternatives that were considered, along with their pros and cons. Each alternative should be clearly separated @@ -37,18 +40,20 @@ Pay close attention to the following aspects of the library: - Performance implications, as performance is one of the main goals of the library. - Dependencies and supported platforms. Does the proposal bring any new dependencies or affect the supported configurations? +- Consistency and possible interaction with the existing library functionality. Include short explanation and links to the related proposals, if any. -Sub-proposals could be organized as separate standalone RFCs, but this is +Sub-proposals could be organized as separate stand-alone RFCs, but this is not mandatory. If the related change is insignificant or does not make any sense without the original proposal, describe it in the main RFC. Some other common subsections could be: - Usage examples. - Testing aspects. -- Execution plan (next steps), if approved. +- Next steps (e.g., design review, prototype, etc.), if approved. ## Open Questions List any questions that are not sufficiently elaborated in the proposal, -need more discussion or prototyping experience, etc. +need more discussion or prototyping experience, etc. Indicate at which state +(typically, "proposed" or "experimental") a question should be addressed.