Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Updated RFCs process description to align with oneDPL #1612

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
Open

Updated RFCs process description to align with oneDPL #1612

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
829383f
Updated RFCs process description to align with oneDPL
vossmjp Jan 21, 2025
e21554f
Update rfcs/README.md
vossmjp Jan 22, 2025
991628b
Update rfcs/README.md
vossmjp Jan 22, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
101 changes: 68 additions & 33 deletions rfcs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,51 +12,86 @@ or rejected for implementation in oneTBB.

The possible RFC states are:

1. Initial
2. Proposed
3. Experimental
4. Supported
5. Archived
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 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.
we recommend opening a PR to add a new RFC to the `rfcs/proposed` directory.

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.
Comment on lines +26 to +28
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we want to state somewhere that the RFC process (and the proposed directory) can be used also for proposals containing only the idea and extended motivation, without stating the design and current API (at least on the initial stage)?

Or the idea is to use discussions for such cases?


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

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 `<feature>_<extension_description>`. 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
`<library_feature>_<extension_description>`. 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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
of what is required to move it from experimental to fully supported -- for
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 oneDPL specification
vossmjp marked this conversation as resolved.
Show resolved Hide resolved
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

Expand Down
Loading