[RFCs] Add rfcs directory

rfcs/README.md

@@ -0,0 +1,70 @@
+# oneTBB Design Documents / RFCs
+
+The purpose of the RFC process is to communicate the intent to make
+library-wide changes, get feedback prior to the actual implementation,
+increase the transparency on why and how decisions are made, and improve
+the alignment between different teams involved in oneTBB development.
+
+This directory documents design documents (RFCs) that have been approved 
+for implementation in oneTBB. 
+
+There are several possible states for an RFC:
+
+1. Initial RFC PR
+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 leads to an idea for a modification 
+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). The modified
+template should be placed in subdirectory of the `rfcs/proposed` with a name
+of the form `<feature>_<extension_description>`. For example,
+a proposal for a new "my_op" flow graph node might be put into a directory
+`rfcs/proposed/flow_graph_my_op_node`. The [template.md](template.md) should
+be used to create the `README.md` file in that directory. The folder can 
+contain other files referenced by the `README.md` file, such as figures.
+
+When two maintainers approve the PR it will be merged to the `rfcs/proposed`
+directory. As the RFC moves to different states, the RFC document should be 
+updated with additional information.
+
+A proposal that is subsequently implemented and released in oneTBB 
+as a preview feature will be moved to 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 support feature in the `rfcs/supported` directory should 
+have a link to the section in the oneTBB specification that has its 
+formal wording.
+
+A feature that is deprecated or removed or a proposal that is abandoned may be moved to the `rfcs/archived` folder.
+
+## Document Style
+
+The design documents are stored in the `rfcs` directory.
+
+- Each RFC is stored in a separate subdirectory
+  `rfcs/proposed/<feature>_<extension_description>`
+- 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 body of the RFC should be based on [template.md](template.md)
+  - The directory can contain other supporting files, such as images, tex formulas, and sub-proposals / sub-RFCs.
+  - It is not required to use the markdown file format based on the exact
+    template file for writing RFCs. However, it is strongly recommended to use
+    text-based file format that can be rendered by GitHub to allow for easy
+    collaboration using PR comments. Even so, files such as pdfs may be
+    acceptable.
+- If the RFC is written in markdown. The width of the text should be limited by
+  80 symbols, unless there is a need to violate this rule, e.g. because of
+  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,13 @@
+# Archived Design Documents
+
+Documents may appear in the `rfcs/archived` directory for one of 
+three reasons:
+
+1. The document describes a feature or extension that has been deprecated and then removed.
+2. The document describes a feature or extension that was proposed but did
+not (ultimately) become a fully support feature. 
+
+Design documents that appear in the `rfcs/archived` folder should include a 
+section that describes why the document has been archived. 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,28 @@
+# Design documents for experimental features
+
+Experimental proposals describe extensions that have been implemented and
+have been 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. It should also have sufficient tests.
+
+An experimental feature does not yet appear as part of the oneTBB 
+specification and therefore its interface and design can still change.
+There is no commitment to backwards compatibility for a preview
+feature.
+
+Since documents in this directory describe preview features, they
+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 have been opened
+against the specification.
+
+Proposals should not remain in the experimental directory forever. The 
+expectation is that the proposals will eventually move either to the
+supported folder when they become fully supported or to 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.

rfcs/proposed/README.md

@@ -0,0 +1,10 @@
+# Design documents for proposed features
+
+Proposed features have reached some level of consensus within the 
+community. A proposal appears in this directory because the
+community believes it has merit and further work should be done.
+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 describe the motivation,
+design and open questions related to the proposed extension.

rfcs/supported/README.md

@@ -0,0 +1,11 @@
+# Design documents for supported features
+
+Supported proposals describe extensions that have been 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.

rfcs/template.md

@@ -0,0 +1,68 @@
+# 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 that are supported by the extension.
+- The expected performance benefit for a modification. 
+- The interface of extensions including class definitions or function 
+declarations.
+
+A proposal should include the alternatives that were considered with listed
+pros and cons. The alternatives should be clearly separated to make possible
+discussions clear.
+
+Pay close attention to the following aspects of the library:
+- API and ABI backwards 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.
+- Listing 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 changes is insignificant, or doesn't make any sense
+  without the original proposal it is fine to have it in the RFC.
+- Execution plan if approved, aka next steps.
+
+## Process Specific Information
+
+Depending on the state of the proposal, additional information should be
+included.
+
+For new proposals (i.e., those in the `rfcs/proposed` directory), list any
+open questions.
+
+For proposals released as preview features that are in the `rfcs/experimental`
+directory, list the exit conditions to move from preview to fully supported.
+These conditions might include demonstrated performance improvements,
+acceptance of specification changes, etc.
+
+For proposals in the `rfcs/supported` directory, provide a link to the
+any section(s) in the oneTBB specification that related to the proposal.
+For modifications that do not affect the public API, no link is needed.