Skip to content

Commit 2a7e0db

Browse files
vossmjpaleksei-fedotovaepanchiPavel Kumbrasev
authored
[RFCs] Add rfcs directory (#1464)
* Add rfcs directory --------- Co-authored-by: Aleksei Fedotov <[email protected]> Co-authored-by: Alexandra <[email protected]> Co-authored-by: Pavel Kumbrasev <[email protected]>
1 parent 4b02f62 commit 2a7e0db

File tree

6 files changed

+195
-0
lines changed

6 files changed

+195
-0
lines changed

‎rfcs/README.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# oneTBB Design Documents/RFCs
2+
3+
The RFC process intends to:
4+
5+
- Communicate library-wide changes
6+
- Collect feedback before implementation
7+
- Increase transparency in decision-making
8+
- Align different teams involved in oneTBB development
9+
10+
This directory contains design documents (RFCs) approved
11+
or rejected for implementation in oneTBB.
12+
13+
The possible RFC states are:
14+
15+
1. Initial
16+
2. Proposed
17+
3. Experimental
18+
4. Supported
19+
5. Archived
20+
21+
Most modifications or new features will naturally start as a part of a
22+
GitHub issue or discussion. Small changes do not require a formal RFC.
23+
However, if the issue or discussion results in an idea for a significant
24+
change or new feature that affects the library's public API or architecture,
25+
we recommend opening a PR to add a new RFC to the `rfcs/proposed` directory.
26+
The RFC should provide a detailed description and design of the proposed feature.
27+
or new feature that significantly impacts the library's public API or
28+
architecture, it will be suggested that a PR be opened to add a new rfc
29+
to the `rfcs/proposed` directory. The RFC contains a more detailed description
30+
and design for the feature.
31+
32+
## General Process
33+
34+
A template for RFCs is available as [template.md](template.md). Place the modified
35+
template in the subdirectory of the `rfcs/proposed` with a name
36+
of the form `<feature>_<extension_description>`. For example,
37+
a proposal for a new ``my_op`` flow graph node should be put into the
38+
`rfcs/proposed/flow_graph_my_op_node` directory. Use [template.md](template.md)
39+
to create the `README.md` file in that directory. The folder can
40+
contain other files referenced by the `README.md` file, such as figures.
41+
42+
Once two maintainers approve the PR, it is merged into the `rfcs/proposed`
43+
directory. Update the RFC document with additional information as the RFC moves
44+
to different states.
45+
46+
A proposal that is subsequently implemented and released in oneTBB
47+
as a preview feature is moved into the `rfcs/experimental` folder. The
48+
RFC for a preview feature in `rfcs/experimental` should include a description
49+
of what is required to move from experimental to fully supported -- for
50+
example, feedback from users, demonstrated performance improvements, etc.
51+
52+
A proposal that is implemented, added to the oneTBB specification, and
53+
supported as a full feature appears in the `rfcs/supported` directory. An RFC
54+
for a fully supported feature in the `rfcs/supported` directory should
55+
have a link to the section in the oneTBB specification with its
56+
formal wording.
57+
58+
A feature that is removed or a proposal that is abandoned or rejected will
59+
be moved to the `rfcs/archived` folder.
60+
61+
## Document Style
62+
63+
The design documents are stored in the `rfcs` directory, and each RFC is placed
64+
in its subdirectory under `rfcs/proposed/<feature>_<extension_description>`.
65+
66+
- There must be a `README.md` file that contains the main RFC itself (or
67+
links to a file that contains it in the same directory).
68+
- The RFC should follow the [template.md](template.md) structure.
69+
- The directory can contain other supporting files, such as images, tex
70+
formulas, and sub-proposals / sub-RFCs.
71+
- We highly recommend using a text-based file format like markdown for easy
72+
collaboration on GitHub, but other formats like PDFs may also be acceptable.
73+
- For the markdown-written RFC, keep the text width within
74+
100 characters, unless there is a reason to violate this rule, e.g.,
75+
long links or wide tables.
76+
- It is also recommended to read through existing RFCs to better understand the
77+
general writing style and required elements.

‎rfcs/archived/README.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Archived Design Documents
2+
3+
Documents may appear in the `rfcs/archived` directory for one of
4+
two reasons:
5+
6+
1. The document describes a feature or extension that has been deprecated and
7+
then removed.
8+
2. The document describes a proposed feature or extension that have
9+
not (ultimately) become a fully supported feature.
10+
11+
Design documents that appear in the `rfcs/archived` folder should describe a
12+
reason for archiving. Documents may
13+
remain in this folder indefinitely to serve as a source of information about
14+
previous proposals and features.

‎rfcs/experimental/README.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# Design Documents for Experimental Features
2+
3+
Experimental proposals describe extensions that are implemented and
4+
released as preview features in the oneTBB library. A preview
5+
feature is expected to have an implementation that is of comparable quality
6+
to a fully supported feature. Sufficient tests are required.
7+
8+
An experimental feature does not yet appear as part of the oneTBB
9+
specification. Therefore, the interface and design can change.
10+
There is no commitment to backward compatibility for a preview
11+
feature.
12+
13+
The documents in this directory
14+
should include a list of the exit conditions that need to be met to move from
15+
preview to fully supported. These conditions might include demonstrated
16+
performance improvements, demonstrated interest from the community,
17+
acceptance of the required oneTBB specification changes, etc.
18+
19+
For features that require oneTBB specification changes, the document might
20+
include wording for those changes or a link to any PRs that opened
21+
against the specification.
22+
23+
Proposals should not remain in the experimental directory forever.
24+
It should move either to the
25+
supported folder when they become fully supported or the archived
26+
folder if they are not fully accepted. It should be highly unusual for
27+
a proposal to stay in the experimental folder for longer than a year or
28+
two.

‎rfcs/proposed/README.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# Design Documents for Proposed Features
2+
3+
Proposed features in this directory have reached some level of consensus within the
4+
community, indicating that they have potential and deserve further development.
5+
However, the proposed changes have not yet been released as a
6+
preview or fully supported feature of the library.
7+
8+
RFCs in the `rfcs/proposed` directory should explain the motivation,
9+
design, and open questions related to the proposed extension.

‎rfcs/supported/README.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Design Documents for Supported Features
2+
3+
Supported proposals describe extensions implemented and
4+
released as fully supported features of the oneTBB library. A fully supported
5+
feature has a high-quality implementation. If the proposal impacted the
6+
public API of the library, it should appear in the oneTBB specification and
7+
have supporting documentation in the oneTBB Reference as needed. A fully
8+
supported feature is regularly tested.
9+
10+
Proposals that appear in `rfcs/supported` may be retained indefinitely to
11+
provide insight into the design of existing features.

‎rfcs/template.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
# Descriptive Name for the Proposal
2+
3+
## Introduction
4+
5+
Short description of the idea proposed with explained motivation.
6+
7+
The motivation could be:
8+
- Improved users experience for API changes and extensions. Code snippets to
9+
showcase the benefits would be nice here.
10+
- Performance improvements with the data, if available.
11+
- Improved engineering practices.
12+
13+
Introduction may also include any additional information that sheds light on
14+
the proposal, such as history of the matter, links to relevant issues and
15+
discussions, etc.
16+
17+
## Proposal
18+
19+
A full and detailed description of the proposal with highlighted consequences.
20+
21+
Depending on the kind of the proposal, the description should cover:
22+
23+
- New use cases supported by the extension.
24+
- The expected performance benefit for a modification.
25+
- The interface of extensions including class definitions or function
26+
declarations.
27+
28+
A proposal should clearly outline the alternatives that were considered,
29+
along with their pros and cons. Each alternative should be clearly separated
30+
to make discussions easier to follow.
31+
32+
Pay close attention to the following aspects of the library:
33+
- API and ABI backward compatibility. The library follows semantic versioning
34+
so if any of those interfaces are to be broken, the RFC needs to state that
35+
explicitly.
36+
- Performance implications, as performance is one of the main goals of the library.
37+
- Changes to the build system. While the library's primary building system is
38+
CMake, there are some frameworks that may build the library directly from the sources.
39+
- Dependencies and support matrix: does the proposal bring any new
40+
dependencies or affect the supported configurations?
41+
42+
Some other common subsections here are:
43+
- Discussion: some people like to list all the options first (as separate
44+
subsections), and then have a dedicated section with the discussion.
45+
- List of the proposed API and examples of its usage.
46+
- Testing aspects.
47+
- Short explanation and links to the related sub-proposals, if any. Such
48+
sub-proposals could be organized as separate standalone RFCs, but this is
49+
not mandatory. If the change is insignificant or doesn't make any sense
50+
without the original proposal, you can have it in the RFC.
51+
- Execution plan (next steps), if approved.
52+
53+
## Open Questions
54+
55+
For new proposals (i.e., those in the `rfcs/proposed` directory), list any
56+
open questions.

0 commit comments

Comments
 (0)