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.

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

Add the directory structure for RFC documents #1878

Merged
merged 5 commits into from
Oct 4, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
98 changes: 98 additions & 0 deletions rfcs/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,98 @@
# oneDPL Design Documents/RFCs

The Request for Comments (RFC) process intends to:

- Propose and discuss ideas for the library evolution.
- Communicate anticipated library-wide changes.
- Collect feedback before implementation.
- Increase transparency in decision-making.
- Align different teams involved in the library development.

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 creating a formal document that provides
a detailed description and design of the proposed feature.

This directory contains design documents (RFCs) approved,
implemented, or rejected for implementation.

## RFC Directory Structure

The design documents are stored in the `rfcs` directory, each placed
in a subdirectory under an `rfcs/<state>` directory. The possible states are:

1. Proposed
2. Experimental
3. Supported
danhoeflinger marked this conversation as resolved.
Show resolved Hide resolved
4. Archived

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.

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.
dmitriy-sobolev marked this conversation as resolved.
Show resolved Hide resolved

The `rfcs/archived` directory contains rejected proposals and documents for
the former functionality that has been removed.
dmitriy-sobolev marked this conversation as resolved.
Show resolved Hide resolved

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

You can collect initial feedback on an idea and input for a formal RFC proposal
using a GitHub discussion. Add the "RFC" label to the discussion to indicate
the intent. The discussion can also be used to reference relevant information
and keep track of the progress.

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 adding a bitonic sorting algorithm working with C++ ranges would be put
into the `rfcs/proposed/range_algorithms_bitonic_sort` 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
as an RFC proposed for implementation.

As the RFC moves to different states, use new PRs to update the RFC document
with additional information.

A proposal that is subsequently implemented and released as an experimental feature
is moved into the `rfcs/experimental` folder.
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 as a fully supported feature appears
in the `rfcs/supported` directory. It typically involves the oneDPL 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. It should state the reasons for
rejection or removal.

## Document Style Recommendations

- Follow the document structure described in [template.md](template.md).
- 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.
14 changes: 14 additions & 0 deletions rfcs/archived/README.md
Original file line number Diff line number Diff line change
@@ -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 has
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.
26 changes: 26 additions & 0 deletions rfcs/experimental/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
# Design Documents for Experimental Features

Experimental proposals describe extensions that are implemented and
released as experimental features in the library. An experimental
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 oneDPL
specification. Therefore, the interface and design can change.
There is no commitment to backward compatibility for experimental features.

The documents in this directory should include a list of the exit conditions
that need to be met to move the functionality from experimental to fully supported.
These conditions might include demonstrated performance improvements,
demonstrated interest from the community,
acceptance of the required specification changes, etc.

For features that require specification changes, the document might
include wording for those changes or a link to any PRs opened
against the specification.

Proposals in the `rfcs/experimental` directory do not remain there indefinitely.
They should move either to `rfcs/supported` when they become fully supported
or to `rfcs/archived` if the corresponding feature is not finally accepted but removed.
As a general rule, a proposal should not stay in the experimental folder
for longer than a year or two.
9 changes: 9 additions & 0 deletions rfcs/proposed/README.md
Original file line number Diff line number Diff line change
@@ -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 implemented 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.
12 changes: 12 additions & 0 deletions rfcs/supported/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
# Design Documents for Supported Features

Supported proposals describe functionality implemented and
released as fully supported features of the library. A fully supported feature
has a high-quality implementation, is regularly tested and properly documented.

If the proposal impacted the public API of the library, it should usually involve
changes in the oneDPL specification. The RFC document should, in that case,
have a link to the formal wording in the specification.

Proposals that appear in `rfcs/supported` may be retained indefinitely to
provide insight into the design of existing features.
54 changes: 54 additions & 0 deletions rfcs/template.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
# Descriptive Name for the Proposal

## Introduction

Replace the text in this section with a short description of the proposed idea.

Explain the motivation for a proposal, such as:
- Improved user experience for API changes and extensions. Code snippets to
showcase the benefits would be nice here.
- Performance improvements.
- Improved engineering practices.

The introduction may also include any additional information that sheds light on
the proposal, such as the history of the matter, links to relevant issues and
discussions, etc.

## Proposal

Replace the text in this section with 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, supported with the data, if available.
- The API of extensions such as class definitions and 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. Or, if you prefer, list all the alternatives
first (perhaps as subsections), and then have a dedicated section with the discussion.

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.
- Dependencies and supported platforms. Does the proposal bring any new
dependencies or affect the supported configurations?

Include short explanation and links to the related proposals, if any.
Sub-proposals could be organized as separate standalone RFCs, but this is
not mandatory. If the related change is insignificant or does not make any sense
without the original proposal, describe it in the main RFC.

Some other common subsections could be:
- Usage examples.
- Testing aspects.
- Execution plan (next steps), if approved.

## Open Questions

List any questions that are not sufficiently elaborated in the proposal,
need more discussion or prototyping experience, etc.
Loading