diff --git a/rfcs/README.md b/rfcs/README.md index 15995290bd..3216d42414 100644 --- a/rfcs/README.md +++ b/rfcs/README.md @@ -12,51 +12,88 @@ 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. +1. Proposed +2. Experimental +3. Supported +4. 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 `rfcs/proposed` directory contains RFCs for proposals that are suggested for +implementation. A proposal may initially be merged into the proposed directory +that contains only an extended motivation and an idea for a solution. Later on, it +may be iteratively refined but eventually 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 plain text file `README`, such as 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. You can add the "RFC" label to the discussion +to indicate the intent. + +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 a `new my_op flow graph node` should be put into the +`rfcs/proposed/flow_graph_my_op_node` 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. + +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` 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. -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 oneTBB 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. +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