Add the directory structure for RFC documents (#1878)

Co-authored-by: Matthew Michel <[email protected]>

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/<state>` 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 `<library_feature>_<extension_description>`
+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
+`<library_feature>_<extension_description>`. 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.

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.

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.

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.

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.

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.