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.