From c97070f1bd5d8a3fbf0d25483c27e46d351ab059 Mon Sep 17 00:00:00 2001 From: Alexey Kukanov Date: Fri, 4 Oct 2024 13:42:27 +0200 Subject: [PATCH] Add the directory structure for RFC documents (#1878) Co-authored-by: Matthew Michel <106704043+mmichel11@users.noreply.github.com> --- rfcs/README.md | 98 +++++++++++++++++++++++++++++++++++++ rfcs/archived/README.md | 14 ++++++ rfcs/experimental/README.md | 26 ++++++++++ rfcs/proposed/README.md | 9 ++++ rfcs/supported/README.md | 12 +++++ rfcs/template.md | 54 ++++++++++++++++++++ 6 files changed, 213 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..c56ed6cb04 --- /dev/null +++ b/rfcs/README.md @@ -0,0 +1,98 @@ +# oneDPL Design Documents/RFCs + +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. + +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 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 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 + +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 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 +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 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. 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/archived/README.md b/rfcs/archived/README.md new file mode 100644 index 0000000000..6ddf16e5b1 --- /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 has +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..bd5b010d59 --- /dev/null +++ b/rfcs/experimental/README.md @@ -0,0 +1,26 @@ +# Design Documents for Experimental Features + +Experimental proposals describe extensions that are implemented and +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 +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. + +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 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/proposed/README.md b/rfcs/proposed/README.md new file mode 100644 index 0000000000..9a848ad6eb --- /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 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. diff --git a/rfcs/supported/README.md b/rfcs/supported/README.md new file mode 100644 index 0000000000..b193c62a2c --- /dev/null +++ b/rfcs/supported/README.md @@ -0,0 +1,12 @@ +# Design Documents for Supported Features + +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 new file mode 100644 index 0000000000..db229ed70c --- /dev/null +++ b/rfcs/template.md @@ -0,0 +1,54 @@ +# Descriptive Name for the Proposal + +## Introduction + +Replace the text in this section with a short description of the proposed idea. + +Explain the motivation for a proposal, such as: +- Improved user experience for API changes and extensions. Code snippets to + showcase the benefits would be nice here. +- Performance improvements. +- Improved engineering practices. + +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 + +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, supported with the data, if available. +- 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. 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 or affect the supported configurations? + +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 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. + +## Open Questions + +List any questions that are not sufficiently elaborated in the proposal, +need more discussion or prototyping experience, etc.