From 5ba5725c7dab604aad12292f734e1c00ba714688 Mon Sep 17 00:00:00 2001 From: Alexey Kukanov Date: Thu, 26 Sep 2024 15:40:20 +0200 Subject: [PATCH 1/5] The initial copy from the oneTBB proposal --- rfcs/README.md | 77 +++++++++++++++++++++++++++++++++++++ rfcs/archived/README.md | 14 +++++++ rfcs/experimental/README.md | 28 ++++++++++++++ rfcs/proposed/README.md | 9 +++++ rfcs/supported/README.md | 11 ++++++ rfcs/template.md | 56 +++++++++++++++++++++++++++ 6 files changed, 195 insertions(+) create mode 100644 rfcs/README.md create mode 100644 rfcs/archived/README.md create mode 100644 rfcs/experimental/README.md create mode 100644 rfcs/proposed/README.md create mode 100644 rfcs/supported/README.md create mode 100644 rfcs/template.md diff --git a/rfcs/README.md b/rfcs/README.md new file mode 100644 index 0000000000..15995290bd --- /dev/null +++ b/rfcs/README.md @@ -0,0 +1,77 @@ +# oneTBB Design Documents/RFCs + +The RFC process intends to: + +- Communicate library-wide changes +- Collect feedback before implementation +- Increase transparency in decision-making +- Align different teams involved in oneTBB development + +This directory contains design documents (RFCs) approved +or rejected for implementation in oneTBB. + +The possible RFC states are: + +1. Initial +2. Proposed +3. Experimental +4. Supported +5. Archived + +Most modifications or new features will naturally start as a part of a +GitHub issue or discussion. Small changes do not require a formal RFC. +However, if the issue or discussion results in an idea for a significant +change or new feature that affects the library's public API or architecture, +we recommend opening a PR to add a new RFC to the `rfcs/proposed` directory. +The RFC should provide a detailed description and design of the proposed feature. +or new feature that significantly impacts the library's public API or +architecture, it will be suggested that a PR be opened to add a new rfc +to the `rfcs/proposed` directory. The RFC contains a more detailed description +and design for the feature. + +## General Process + +A template for RFCs is available as [template.md](template.md). Place the modified +template in the subdirectory of the `rfcs/proposed` with a name +of the form `_`. For example, +a proposal for a new ``my_op`` flow graph node should be put into the +`rfcs/proposed/flow_graph_my_op_node` directory. Use [template.md](template.md) +to create the `README.md` file in that directory. The folder can +contain other files referenced by the `README.md` file, such as figures. + +Once two maintainers approve the PR, it is merged into the `rfcs/proposed` +directory. Update the RFC document with additional information as the RFC moves +to different states. + +A proposal that is subsequently implemented and released in oneTBB +as a preview feature is moved into the `rfcs/experimental` folder. The +RFC for a preview feature in `rfcs/experimental` should include a description +of what is required to move from experimental to fully supported -- for +example, feedback from users, demonstrated performance improvements, etc. + +A proposal that is implemented, added to the oneTBB specification, and +supported as a full feature appears in the `rfcs/supported` directory. An RFC +for a fully supported feature in the `rfcs/supported` directory should +have a link to the section in the oneTBB 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. + +## Document Style + +The design documents are stored in the `rfcs` directory, and each RFC is placed +in its subdirectory under `rfcs/proposed/_`. + +- There must be a `README.md` file that contains the main RFC itself (or +links to a file that contains it in the same directory). + - The RFC should follow the [template.md](template.md) structure. + - The directory can contain other supporting files, such as images, tex + formulas, and sub-proposals / sub-RFCs. + - We highly recommend using a text-based file format like markdown for easy + collaboration on GitHub, but other formats like PDFs may also be acceptable. +- For the markdown-written RFC, keep the text width within + 100 characters, unless there is a reason to violate this rule, e.g., + long links or wide tables. +- It is also recommended to read through existing RFCs to better understand the +general writing style and required elements. diff --git a/rfcs/archived/README.md b/rfcs/archived/README.md new file mode 100644 index 0000000000..7c23aa3efe --- /dev/null +++ b/rfcs/archived/README.md @@ -0,0 +1,14 @@ +# Archived Design Documents + +Documents may appear in the `rfcs/archived` directory for one of +two reasons: + +1. The document describes a feature or extension that has been deprecated and +then removed. +2. The document describes a proposed feature or extension that have +not (ultimately) become a fully supported feature. + +Design documents that appear in the `rfcs/archived` folder should describe a +reason for archiving. Documents may +remain in this folder indefinitely to serve as a source of information about +previous proposals and features. diff --git a/rfcs/experimental/README.md b/rfcs/experimental/README.md new file mode 100644 index 0000000000..612e69f032 --- /dev/null +++ b/rfcs/experimental/README.md @@ -0,0 +1,28 @@ +# Design Documents for Experimental Features + +Experimental proposals describe extensions that are implemented and +released as preview features in the oneTBB library. A preview +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 oneTBB +specification. Therefore, the interface and design can change. +There is no commitment to backward compatibility for a preview +feature. + +The documents in this directory +should include a list of the exit conditions that need to be met to move from +preview to fully supported. These conditions might include demonstrated +performance improvements, demonstrated interest from the community, +acceptance of the required oneTBB specification changes, etc. + +For features that require oneTBB specification changes, the document might +include wording for those changes or a link to any PRs that opened +against the specification. + +Proposals should not remain in the experimental directory forever. +It should move either to the +supported folder when they become fully supported or the archived +folder if they are not fully accepted. It should be highly unusual for +a proposal to stay in the experimental folder for longer than a year or +two. diff --git a/rfcs/proposed/README.md b/rfcs/proposed/README.md new file mode 100644 index 0000000000..af243fad5e --- /dev/null +++ b/rfcs/proposed/README.md @@ -0,0 +1,9 @@ +# Design Documents for Proposed Features + +Proposed features in this directory have reached some level of consensus within the +community, indicating that they have potential and deserve further development. +However, the proposed changes have not yet been released 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. diff --git a/rfcs/supported/README.md b/rfcs/supported/README.md new file mode 100644 index 0000000000..ebbb35150d --- /dev/null +++ b/rfcs/supported/README.md @@ -0,0 +1,11 @@ +# Design Documents for Supported Features + +Supported proposals describe extensions implemented and +released as fully supported features of the oneTBB library. A fully supported +feature has a high-quality implementation. If the proposal impacted the +public API of the library, it should appear in the oneTBB specification and +have supporting documentation in the oneTBB Reference as needed. A fully +supported feature is regularly tested. + +Proposals that appear in `rfcs/supported` may be retained indefinitely to +provide insight into the design of existing features. diff --git a/rfcs/template.md b/rfcs/template.md new file mode 100644 index 0000000000..834840a5ea --- /dev/null +++ b/rfcs/template.md @@ -0,0 +1,56 @@ +# Descriptive Name for the Proposal + +## Introduction + +Short description of the idea proposed with explained motivation. + +The motivation could be: +- Improved users experience for API changes and extensions. Code snippets to + showcase the benefits would be nice here. +- Performance improvements with the data, if available. +- Improved engineering practices. + +Introduction may also include any additional information that sheds light on +the proposal, such as history of the matter, links to relevant issues and +discussions, etc. + +## Proposal + +A full and detailed description of the proposal with highlighted consequences. + +Depending on the kind of the proposal, the description should cover: + +- New use cases supported by the extension. +- The expected performance benefit for a modification. +- The interface of extensions including class definitions or function +declarations. + +A proposal should clearly outline the alternatives that were considered, +along with their pros and cons. Each alternative should be clearly separated +to make discussions easier to follow. + +Pay close attention to the following aspects of the library: +- API and ABI backward compatibility. The library follows semantic versioning + so if any of those interfaces are to be broken, the RFC needs to state that + explicitly. +- Performance implications, as performance is one of the main goals of the library. +- Changes to the build system. While the library's primary building system is + CMake, there are some frameworks that may build the library directly from the sources. +- Dependencies and support matrix: does the proposal bring any new + dependencies or affect the supported configurations? + +Some other common subsections here are: +- Discussion: some people like to list all the options first (as separate + subsections), and then have a dedicated section with the discussion. +- List of the proposed API and examples of its usage. +- Testing aspects. +- Short explanation and links to the related sub-proposals, if any. Such + sub-proposals could be organized as separate standalone RFCs, but this is + not mandatory. If the change is insignificant or doesn't make any sense + without the original proposal, you can have it in the RFC. +- Execution plan (next steps), if approved. + +## Open Questions + +For new proposals (i.e., those in the `rfcs/proposed` directory), list any +open questions. From 670f7753f25fe029f0d073391d40a8be80daee9f Mon Sep 17 00:00:00 2001 From: Alexey Kukanov Date: Fri, 27 Sep 2024 16:00:56 +0200 Subject: [PATCH 2/5] Remove references to oneTBB and its specifics. Improve the structure and wording. --- rfcs/README.md | 139 +++++++++++++++++++++--------------- rfcs/experimental/README.md | 21 +++--- rfcs/proposed/README.md | 2 +- rfcs/supported/README.md | 13 ++-- rfcs/template.md | 40 +++++------ 5 files changed, 118 insertions(+), 97 deletions(-) diff --git a/rfcs/README.md b/rfcs/README.md index 15995290bd..d10f3df1f4 100644 --- a/rfcs/README.md +++ b/rfcs/README.md @@ -1,77 +1,98 @@ -# oneTBB Design Documents/RFCs +# oneDPL Design Documents/RFCs -The RFC process intends to: +The Request for Comments (RFC) process intends to: -- Communicate library-wide changes +- Propose and discuss ideas for the library evolution +- Communicate anticipated library-wide changes - Collect feedback before implementation - Increase transparency in decision-making -- Align different teams involved in oneTBB development - -This directory contains design documents (RFCs) approved -or rejected for implementation in oneTBB. - -The possible RFC states are: - -1. Initial -2. Proposed -3. Experimental -4. Supported -5. Archived +- Align different teams involved in the library development Most modifications or new features will naturally start as a part of a GitHub issue or discussion. Small changes do not require a formal RFC. However, if the issue or discussion results in an idea for a significant change or new feature that affects the library's public API or architecture, -we recommend opening a PR to add a new RFC to the `rfcs/proposed` directory. -The RFC should provide a detailed description and design of the proposed feature. -or new feature that significantly impacts the library's public API or -architecture, it will be suggested that a PR be opened to add a new rfc -to the `rfcs/proposed` directory. The RFC contains a more detailed description -and design for the feature. +we recommend creating a formal document that provides +a detailed description and design of the proposed feature. + +This directory contains design documents (RFCs) approved, +implemented, or rejected for implementation. + +## RFC Directory Structure + +The design documents are stored in the `rfcs` directory, each placed +in a subdirectory under an `rfcs/` directory. The possible states are: + +1. Proposed +2. Experimental +3. Supported +4. Archived + +The `rfcs/proposed` directory contains RFCs for approved proposals +that yet need to be implemented. These documents describe the overall design +and API for the proposed functionality. + +The `rfcs/experimental` directory contains RFCs for experimental library features. +In addition to the design, these documents describe the criteria for the described +functionality to exit the experimental status. + +The `rfcs/supported` directory contains documents for the fully supported features, +both implemented according to the library specification and provided as extensions. + +The `rfcs/archived` directory contains rejected proposals and documents for +the former functionality that has been removed. + +A subdirectory for an RFC should have a name of the form `_` +and should contain a `README.md` file that either is the RFC document +or links to other files and Web resources that describe the functionality. +The directory can contain other supporting files such as images or formulas, +as well as sub-proposals / sub-RFCs. ## General Process -A template for RFCs is available as [template.md](template.md). Place the modified -template in the subdirectory of the `rfcs/proposed` with a name -of the form `_`. For example, -a proposal for a new ``my_op`` flow graph node should be put into the -`rfcs/proposed/flow_graph_my_op_node` directory. Use [template.md](template.md) -to create the `README.md` file in that directory. The folder can -contain other files referenced by the `README.md` file, such as figures. - -Once two maintainers approve the PR, it is merged into the `rfcs/proposed` -directory. Update the RFC document with additional information as the RFC moves -to different states. - -A proposal that is subsequently implemented and released in oneTBB -as a preview feature is moved into the `rfcs/experimental` folder. The -RFC for a preview feature in `rfcs/experimental` should include a description -of what is required to move from experimental to fully supported -- for +You can collect initial feedback on an idea and input for a formal RFC proposal +using a GitHub discussion. Add the "RFC" label to the discussion to indicate +the intent. The discussion can also be used to reference relevant information +and keep track of the progress. + +To create a new RFC document, open a pull request (PR) to add it to the `rfcs/proposed` directory. +A template for new RFCs is available as [template.md](template.md). +Use it to create the `README.md` file in a subdirectory of `rfcs/proposed` named +`_`. For example, +a proposal for adding a bitonic sorting algorithm working with C++ ranges would be put +into the `rfcs/proposed/range_algorithms_bitonic_sort` directory. +Put other files referenced by the `README.md` file, such as figures, into the same directory. +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 at least two maintainers approve the PR, it is merged into the main branch +as an RFC proposed for implementation. + +As the RFC moves to different states, use new PRs to update the RFC document +with additional information. + +A proposal that is subsequently implemented and released as an experimental feature +is moved into the `rfcs/experimental` folder. +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. -A proposal that is implemented, added to the oneTBB specification, and -supported as a full feature appears in the `rfcs/supported` directory. An RFC -for a fully supported feature in the `rfcs/supported` directory should -have a link to the section in the oneTBB specification with its -formal wording. +A proposal that is implemented as a fully supported feature appears +in the `rfcs/supported` directory. It typically involves the oneDPL specification +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. - -## Document Style - -The design documents are stored in the `rfcs` directory, and each RFC is placed -in its subdirectory under `rfcs/proposed/_`. - -- There must be a `README.md` file that contains the main RFC itself (or -links to a file that contains it in the same directory). - - The RFC should follow the [template.md](template.md) structure. - - The directory can contain other supporting files, such as images, tex - formulas, and sub-proposals / sub-RFCs. - - We highly recommend using a text-based file format like markdown for easy - collaboration on GitHub, but other formats like PDFs may also be acceptable. -- For the markdown-written RFC, keep the text width within - 100 characters, unless there is a reason to violate this rule, e.g., - long links or wide tables. +be moved to the `rfcs/archived` folder. It should state the reasons for +rejection or removal. + +## Document Style Recommendations + +- Follow the document structure described in [template.md](template.md). +- We highly recommend using a text-based file format like markdown for easy +collaboration on GitHub, but other formats like PDFs may also be acceptable. +- For the markdown-written RFC, keep the text width within 100 characters, +unless there is a reason to violate this rule, e.g., long links or wide tables. - It is also recommended to read through existing RFCs to better understand the general writing style and required elements. diff --git a/rfcs/experimental/README.md b/rfcs/experimental/README.md index 612e69f032..9107b0879c 100644 --- a/rfcs/experimental/README.md +++ b/rfcs/experimental/README.md @@ -1,28 +1,27 @@ # Design Documents for Experimental Features Experimental proposals describe extensions that are implemented and -released as preview features in the oneTBB library. A preview +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 oneTBB +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 a preview -feature. +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 from -preview to fully supported. These conditions might include demonstrated +experimental to fully supported. These conditions might include demonstrated performance improvements, demonstrated interest from the community, -acceptance of the required oneTBB specification changes, etc. +acceptance of the required specification changes, etc. -For features that require oneTBB specification changes, the document might -include wording for those changes or a link to any PRs that opened +For features that require specification changes, the document might +include wording for those changes or a link to any PRs opened against the specification. Proposals should not remain in the experimental directory forever. It should move either to the supported folder when they become fully supported or the archived -folder if they are not fully accepted. It should be highly unusual for -a proposal to stay in the experimental folder for longer than a year or -two. +folder if the corresponding feature is not finally accepted but removed. +It should be highly unusual for +a proposal to stay in the experimental folder for longer than a year or two. diff --git a/rfcs/proposed/README.md b/rfcs/proposed/README.md index af243fad5e..9a848ad6eb 100644 --- a/rfcs/proposed/README.md +++ b/rfcs/proposed/README.md @@ -2,7 +2,7 @@ Proposed features in this directory have reached some level of consensus within the community, indicating that they have potential and deserve further development. -However, the proposed changes have not yet been released as a +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, diff --git a/rfcs/supported/README.md b/rfcs/supported/README.md index ebbb35150d..df561630cd 100644 --- a/rfcs/supported/README.md +++ b/rfcs/supported/README.md @@ -1,11 +1,12 @@ # Design Documents for Supported Features -Supported proposals describe extensions implemented and -released as fully supported features of the oneTBB library. A fully supported -feature has a high-quality implementation. If the proposal impacted the -public API of the library, it should appear in the oneTBB specification and -have supporting documentation in the oneTBB Reference as needed. A fully -supported feature is regularly tested. +Supported proposals describe functionality implemented and +released as fully supported features of the library. A fully supported feature +has a high-quality implementation, is regularly tested and properly documented. + +If the proposal impacted the public API of the library, it should usually involve +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. diff --git a/rfcs/template.md b/rfcs/template.md index 834840a5ea..a70bf7aa4c 100644 --- a/rfcs/template.md +++ b/rfcs/template.md @@ -2,28 +2,28 @@ ## Introduction -Short description of the idea proposed with explained motivation. +Replace the text in this section with a short description of the proposed idea. -The motivation could be: +Explain the motivation for a proposal, such as: - Improved users experience for API changes and extensions. Code snippets to showcase the benefits would be nice here. -- Performance improvements with the data, if available. +- Performance improvements. - Improved engineering practices. -Introduction may also include any additional information that sheds light on -the proposal, such as history of the matter, links to relevant issues and +The introduction may also include any additional information that sheds light on +the proposal, such as the history of the matter, links to relevant issues and discussions, etc. ## Proposal -A full and detailed description of the proposal with highlighted consequences. +Replace the text in this section with a full and detailed description of the proposal +with highlighted consequences. Depending on the kind of the proposal, the description should cover: - New use cases supported by the extension. -- The expected performance benefit for a modification. -- The interface of extensions including class definitions or function -declarations. +- The expected performance benefit for a modification, supported with the data, if available. +- The interface of extensions including class definitions or function declarations. A proposal should clearly outline the alternatives that were considered, along with their pros and cons. Each alternative should be clearly separated @@ -34,23 +34,23 @@ Pay close attention to the following aspects of the library: so if any of those interfaces are to be broken, the RFC needs to state that explicitly. - Performance implications, as performance is one of the main goals of the library. -- Changes to the build system. While the library's primary building system is - CMake, there are some frameworks that may build the library directly from the sources. -- Dependencies and support matrix: does the proposal bring any new +- Dependencies and supported platforms: does the proposal bring any new dependencies or affect the supported configurations? -Some other common subsections here are: +Include short explanation and links to the related proposals, if any. +Sub-proposals could be organized as separate standalone RFCs, but this is +not mandatory. If the related change is insignificant or doesn't make any sense +without the original proposal, describe it in the main RFC. + +Some other common subsections could be: - Discussion: some people like to list all the options first (as separate subsections), and then have a dedicated section with the discussion. -- List of the proposed API and examples of its usage. +- Synopsis: the list of the proposed API. +- Usage examples. - Testing aspects. -- Short explanation and links to the related sub-proposals, if any. Such - sub-proposals could be organized as separate standalone RFCs, but this is - not mandatory. If the change is insignificant or doesn't make any sense - without the original proposal, you can have it in the RFC. - Execution plan (next steps), if approved. ## Open Questions -For new proposals (i.e., those in the `rfcs/proposed` directory), list any -open questions. +List any questions that are not sufficiently elaborated in the proposal, +need more discussion or prototyping experience, etc. From 3e3b3c88d73dda13ff6d6229a442a75d062ff651 Mon Sep 17 00:00:00 2001 From: Alexey Kukanov Date: Fri, 27 Sep 2024 17:01:15 +0200 Subject: [PATCH 3/5] Try fixing HTML rendering --- rfcs/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/rfcs/README.md b/rfcs/README.md index d10f3df1f4..385887bfd3 100644 --- a/rfcs/README.md +++ b/rfcs/README.md @@ -64,8 +64,8 @@ into the `rfcs/proposed/range_algorithms_bitonic_sort` directory. Put other files referenced by the `README.md` file, such as figures, into the same directory. 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), +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 at least two maintainers approve the PR, it is merged into the main branch as an RFC proposed for implementation. From 1ffa633f40ea482bbe2729cd1c532967bb412c3d Mon Sep 17 00:00:00 2001 From: Alexey Kukanov Date: Sat, 28 Sep 2024 13:41:35 +0200 Subject: [PATCH 4/5] Address the review feedback --- rfcs/README.md | 14 +++++++------- rfcs/experimental/README.md | 19 +++++++++---------- rfcs/supported/README.md | 4 ++-- rfcs/template.md | 12 +++++------- 4 files changed, 23 insertions(+), 26 deletions(-) diff --git a/rfcs/README.md b/rfcs/README.md index 385887bfd3..c56ed6cb04 100644 --- a/rfcs/README.md +++ b/rfcs/README.md @@ -2,11 +2,11 @@ The Request for Comments (RFC) process intends to: -- Propose and discuss ideas for the library evolution -- Communicate anticipated library-wide changes -- Collect feedback before implementation -- Increase transparency in decision-making -- Align different teams involved in the library development +- Propose and discuss ideas for the library evolution. +- Communicate anticipated library-wide changes. +- Collect feedback before implementation. +- Increase transparency in decision-making. +- Align different teams involved in the library development. Most modifications or new features will naturally start as a part of a GitHub issue or discussion. Small changes do not require a formal RFC. @@ -29,7 +29,7 @@ in a subdirectory under an `rfcs/` directory. The possible states are: 4. Archived The `rfcs/proposed` directory contains RFCs for approved proposals -that yet need to be implemented. These documents describe the overall design +that need to be implemented. These documents describe the overall design and API for the proposed functionality. The `rfcs/experimental` directory contains RFCs for experimental library features. @@ -66,7 +66,7 @@ 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 at least two maintainers approve the PR, it is merged into the main branch +Once two or more maintainers approve the PR, it is merged into the main branch as an RFC proposed for implementation. As the RFC moves to different states, use new PRs to update the RFC document diff --git a/rfcs/experimental/README.md b/rfcs/experimental/README.md index 9107b0879c..bd5b010d59 100644 --- a/rfcs/experimental/README.md +++ b/rfcs/experimental/README.md @@ -9,19 +9,18 @@ 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 from -experimental to fully supported. These conditions might include demonstrated -performance improvements, demonstrated interest from the community, +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. For features that require specification changes, the document might include wording for those changes or a link to any PRs opened against the specification. -Proposals should not remain in the experimental directory forever. -It should move either to the -supported folder when they become fully supported or the archived -folder if the corresponding feature is not finally accepted but removed. -It should be highly unusual for -a proposal to stay in the experimental folder for longer than a year or two. +Proposals in the `rfcs/experimental` directory do not remain there indefinitely. +They should move either to `rfcs/supported` when they become fully supported +or to `rfcs/archived` if the corresponding feature is not finally accepted but removed. +As a general rule, a proposal should not stay in the experimental folder +for longer than a year or two. diff --git a/rfcs/supported/README.md b/rfcs/supported/README.md index df561630cd..b193c62a2c 100644 --- a/rfcs/supported/README.md +++ b/rfcs/supported/README.md @@ -5,8 +5,8 @@ released as fully supported features of the library. A fully supported feature has a high-quality implementation, is regularly tested and properly documented. If the proposal impacted the public API of the library, it should usually involve -changes in the oneDPL specification. The RFC document should in that case have a link -to the formal wording in the specification. +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. diff --git a/rfcs/template.md b/rfcs/template.md index a70bf7aa4c..35e8dab304 100644 --- a/rfcs/template.md +++ b/rfcs/template.md @@ -5,7 +5,7 @@ Replace the text in this section with a short description of the proposed idea. Explain the motivation for a proposal, such as: -- Improved users experience for API changes and extensions. Code snippets to +- Improved user experience for API changes and extensions. Code snippets to showcase the benefits would be nice here. - Performance improvements. - Improved engineering practices. @@ -23,18 +23,19 @@ Depending on the kind of the proposal, the description should cover: - New use cases supported by the extension. - The expected performance benefit for a modification, supported with the data, if available. -- The interface of extensions including class definitions or function declarations. +- The API of extensions such as class definitions and function declarations. A proposal should clearly outline the alternatives that were considered, along with their pros and cons. Each alternative should be clearly separated -to make discussions easier to follow. +to make discussions easier to follow. Or, if you prefer, list all the alternatives +first (perhaps as subsections), and then have a dedicated section with the discussion. Pay close attention to the following aspects of the library: - API and ABI backward compatibility. The library follows semantic versioning so if any of those interfaces are to be broken, the RFC needs to state that explicitly. - Performance implications, as performance is one of the main goals of the library. -- Dependencies and supported platforms: does the proposal bring any new +- Dependencies and supported platforms. Does the proposal bring any new dependencies or affect the supported configurations? Include short explanation and links to the related proposals, if any. @@ -43,9 +44,6 @@ not mandatory. If the related change is insignificant or doesn't make any sense without the original proposal, describe it in the main RFC. Some other common subsections could be: -- Discussion: some people like to list all the options first (as separate - subsections), and then have a dedicated section with the discussion. -- Synopsis: the list of the proposed API. - Usage examples. - Testing aspects. - Execution plan (next steps), if approved. From d9613fed544dc3f9f432db116efe7cf585523fae Mon Sep 17 00:00:00 2001 From: Alexey Kukanov Date: Wed, 2 Oct 2024 14:21:21 +0200 Subject: [PATCH 5/5] Apply suggestions from code review Co-authored-by: Matthew Michel <106704043+mmichel11@users.noreply.github.com> --- rfcs/archived/README.md | 2 +- rfcs/template.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/rfcs/archived/README.md b/rfcs/archived/README.md index 7c23aa3efe..6ddf16e5b1 100644 --- a/rfcs/archived/README.md +++ b/rfcs/archived/README.md @@ -5,7 +5,7 @@ two reasons: 1. The document describes a feature or extension that has been deprecated and then removed. -2. The document describes a proposed feature or extension that have +2. The document describes a proposed feature or extension that has not (ultimately) become a fully supported feature. Design documents that appear in the `rfcs/archived` folder should describe a diff --git a/rfcs/template.md b/rfcs/template.md index 35e8dab304..db229ed70c 100644 --- a/rfcs/template.md +++ b/rfcs/template.md @@ -40,7 +40,7 @@ Pay close attention to the following aspects of the library: Include short explanation and links to the related proposals, if any. Sub-proposals could be organized as separate standalone RFCs, but this is -not mandatory. If the related change is insignificant or doesn't make any sense +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: