| RFC | 1 |
|---|---|
| Author | Harald van Dijk <harald.vandijk@codeplay.com> |
| Status | active |
RFC stands for Request For Comments. An RFC is a design document providing information to the oneAPI Construction Kit community, or describing a new feature for oneAPI Construction Kit or its processes or environment. The RFC should provide a concise technical specification of the feature and a rationale for the feature.
We intend RFCs to be the primary mechanisms for proposing major new features, for collecting community input on an issue, and for documenting the design decisions that have gone into oneAPI Construction Kit. The RFC author is responsible for building consensus within the community and documenting dissenting opinions.
Because the RFCs are maintained as text files in a versioned repository, their revision history is the historical record of the feature proposal. This historical record is available by the normal git commands for retrieving older revisions, and can also be browsed on GitHub.
This process is based on that of the Python Enhancement Proposals and differences between the two are intended to be minimal.
The typical primary audience for RFCs are the core developers of the oneAPI Construction Kit.
However, other parts of the oneAPI Construction Kit community may also choose to use the process to document expected API conventions and to manage complex design coordination problems that require collaboration across multiple projects.
The RFC process begins with a new idea for oneAPI Construction Kit. It is highly recommended that a single RFC contain a single key proposal or new idea; the more focused the RFC, the more successful it is likely to be. Most enhancements and bug fixes do not need an RFC and can be submitted directly to the oneAPI Construction Kit issue tracker. The editors reserve the right to reject RFCs if they appear too unfocused or too broad. If in doubt, split your RFC into several well-focused ones.
Each RFC must have a champion – someone who writes the RFC using the style and format described below, shepherds the discussions in the appropriate forums, and attempts to build community consensus around the idea. The RFC champion (a.k.a. author) should first attempt to ascertain whether the idea is RFC-able. Posting to the Ideas category of oneAPI Construction Kit Discussions is usually the best way to go about this, unless a more specialized venue is appropriate.
Vetting an idea publicly before going as far as writing an RFC is meant to save the potential author time. Asking the community first if an idea is original helps prevent too much time being spent on something that is guaranteed to be rejected based on prior discussions. It also helps to make sure the idea is applicable to the entire community and not just the author. Just because an idea sounds good to the author does not mean it will work for most people in most areas where oneAPI Construction Kit can be used.
Once the champion has asked the oneAPI Construction Kit community as to whether an idea has any chance of acceptance, a draft RFC should be presented. This gives the author a chance to flesh out the draft RFC to make properly formatted, of high quality, and to address initial concerns about the proposal.
Following the above initial discussion, the workflow varies based on whether any of the RFC’s co-authors are core developers. If one or more of the RFC’s co-authors are core developers, they are responsible for following the process outlined below. Otherwise (i.e. none of the co-authors are core developers), then the RFC author(s) will need to find a sponsor for the RFC.
The sponsor’s job is to provide guidance to the RFC author to help them through the logistics of the RFC process (somewhat acting like a mentor). Being a sponsor does not disqualify that person from becoming a co-author or RFC-Delegate later on (but not both). The sponsor of an RFC is recorded in the “sponsor:” field of the header.
Once the sponsor or the core developer(s) co-authoring the RFC deem the RFC ready for submission, the proposal should be submitted as a draft RFC via a GitHub pull request. The draft must be written in RFC style as described below, else it will fail review immediately (although minor errors may be corrected by the editors).
The standard RFC workflow is:
You, the RFC author, fork the oneAPI Construction Kit repository,
check out the rfcs branch, and create a file named rfc-{NNNN}.md that
contains your new RFC. {NNNN} should be the next available RFC number not
used by a published or in-PR RFC.
In the “rfc:” header field, enter the RFC number that matches your filename as your draft RFC number.
Push this to your GitHub fork and submit a pull request.
The RFC editors review your PR for structure, formatting, and other errors. For a formatted RFC, rfc-0002 is provided as a template. Approval criteria are:
The RFC’s language (spelling, grammar, sentence structure, etc.) and code
style (examples should match oneAPI Construction Kit’s clang-format
settings) should be correct and conformant. The RFC text
will be checked for correct Markdown formatting when the pull request is
submitted. RFCs with invalid markup will not be approved.
Editors should generally be quite lenient about this initial review, expecting that problems will be corrected by the reviewing process. Note: Approval of the RFC is no guarantee that there are no embarrassing mistakes! Correctness is the responsibility of authors and reviewers, not the editors.
If the RFC isn’t ready for approval, an editor will send it back to the author for revision, with specific instructions.
Once approved, they will assign your RFC a number.
Once the review process is complete, and the RFC editors approve it (note that
this is not the same as accepting your RFC!), they will squash commit your
pull request onto rfcs.
The RFC editors will not unreasonably deny publication of an RFC. Reasons for denying RFC status include duplication of effort, being technically unsound, or not providing proper motivation or addressing backwards compatibility.
Even developers should submit RFCs via pull request. When doing so, you are generally expected to handle the process yourself; if you need assistance from RFC editors, mention this in your pull request.
Getting an RFC number assigned early can be useful for ease of reference, especially when multiple draft RFCs are being considered at the same time.
As soon as an RFC number has been assigned and the draft RFC is committed to the
rfcs branch, a discussion thread for the RFC should be created to
provide a central place to discuss and review its contents, and the RFC should
be updated so that the discussions-to header links to it.
The RFC authors (or sponsor, if applicable) may select any reasonable venue for the discussion, so long as the the following criteria are met:
discussions-to header.The RFCs category of oneAPI Construction Kit Discussions is the preferred choice for most RFCs.
If an RFC undergoes a significant re-write or other major, substantive changes
to its proposed specification, a new thread should typically be created in the
chosen venue to solicit additional feedback. If this occurs, the
discussions-to link must be updated and a new post-history entry added
pointing to this new thread.
RFC authors are responsible for collecting community feedback on an RFC before submitting it for review. However, to avoid long-winded and open-ended discussions, strategies such as soliciting private or more narrowly-tailored feedback in the early design phase, collaborating with other community members with expertise in the RFC’s subject matter, and picking an appropriately-specialized discussion for the RFC’s topic (if applicable) should be considered. RFC authors should use their discretion here.
Once the RFC is assigned a number and committed to the rfcs branch,
substantive issues should generally be discussed on the canonical public thread,
as opposed to private channels, GitHub pull request reviews or unrelated venues.
This ensures everyone can follow and contribute, avoids fragmenting the
discussion, and makes sure it is fully considered as part of the RFC review
process. Comments, support, concerns and other feedback on this designated
thread are a critical part of what the oneAPI Construction Kit core developers
will consider when reviewing the RFC.
Once the authors have completed an RFC, they may request a review for style and consistency from the RFC editors.
The final authority for RFC approval is the oneAPI Construction Kit core developers.
For a RFC to be accepted it must meet certain minimum criteria. It must be a clear and complete description of the proposed enhancement. The enhancement must represent a net improvement. The proposed implementation, if applicable, must be solid and must not complicate the project unduly. Finally, a proposed enhancement must be in line with the project norms in order to be accepted. (This is intentionally imprecise.)
Once an RFC has been accepted, the reference implementation must be completed.
When the reference implementation is complete and incorporated into the main
source code repository, the status will be changed to final.
A RFC can also be rejected. Perhaps after all is said and done it was not a
good idea. It is still important to have a record of this fact. The withdrawn
status is similar - it means that the RFC author themself has decided that the
RFC is actually a bad idea, or has accepted that a competing proposal is a
better alternative.
When a RFC is accepted, rejected or withdrawn, the RFC should be updated accordingly.
In general, RFCs are no longer substantially modified after they have reached the accepted, final, rejected or superseded state. Once resolution is reached, an RFC is considered a historical document rather than a living specification. Formal documentation of the expected behavior should be maintained elsewhere.
Active RFCs may be updated over time to reflect changes to development practices and other details. The precise process followed in these cases will depend on the nature and purpose of the RFC in question.
Occasionally, a deferred or even a withdrawn RFC may be resurrected with major updates, but it is often better to just propose a new one.
Each RFC should have the following parts/sections:
Preamble – headers containing meta-data about the RFC, including the RFC number, a short descriptive title, the names, and optionally the contact info for each author, etc.
Abstract – a short (~200 word) description of the technical issue being addressed.
Motivation – The motivation is critical for RFCs that want to change the oneAPI Construction Kit. It should clearly explain why the status quo is inadequate to address the problem that the RFC solves. This can include collecting documented support for the RFC from important projects in the oneAPI ecosystem. RFC submissions without sufficient motivation may be rejected.
Rationale – The rationale fleshes out the specification by describing why particular design decisions were made. It should describe alternate designs that were considered and related work, e.g. how the feature is supported in other implementations.
The rationale should provide evidence of consensus within the community and discuss important objections or concerns raised during discussion.
Specification – The technical specification should describe the semantics of any new function. The specification should be detailed enough to allow competing, interoperable implementations.
Backwards Compatibility – All RFCs that introduce backwards incompatibilities must include a section describing these incompatibilities and their severity. The RFC must explain how the author proposes to deal with these incompatibilities. RFC submissions without a sufficient backwards compatibility treatise may be rejected outright.
Security Implications – If there are security concerns in relation to the RFC, those concerns should be explicitly written out to make sure reviewers of the RFC are aware of them.
Reference Implementation – The reference implementation must be completed before any RFC is given status “final”, but it need not be completed before the RFC is accepted. While there is merit to the approach of reaching consensus on the specification and rationale before writing code, the principle of “rough consensus and running code” is still useful when it comes to resolving many discussions of details.
The final implementation must include test code and documentation if appropriate for the nature of the RFC.
Rejected Ideas – Throughout the discussion of an RFC, various ideas may be proposed which are not accepted. Those rejected ideas should be recorded along with the reasoning as to why they were rejected. This both helps record the thought process behind the final version of the RFC as well as preventing people from bringing up the same rejected idea again in subsequent discussions.
In a way this section can be thought of as a breakout section of the Rationale section that is focused specifically on why certain ideas were not ultimately pursued.
Open Issues – While an RFC is in draft, ideas can come up which warrant further discussion. Those ideas should be recorded so people know that they are being thought about but do not have a concrete resolution. This helps make sure all issues required for the RFC to be ready for consideration are complete and reduces people duplicating prior discussion.
Footnotes – A collection of footnotes cited in the RFC, and a place to list non-inline hyperlink targets.
Copyright/license – Each new RFC must be placed under a dual license of public domain and CC0-1.0-Universal (see this RFC for an example).
RFCs are UTF-8 encoded text files using the Markdown format. Markdown allows for rich markup that is still quite easy to read, but also results in good-looking and functional HTML. rfc-0002 contains an RFC template.
The RFC text files are automatically converted to HTML (via a Jekyll-based build system) for easier online reading.
Each RFC must begin with a header preamble. The headers must appear in the following order. Headers marked with “*” are optional and are described below. All other headers are required.
rfc: <rfc number>
title: <rfc title>
author: <list of authors' names and optionally, email addresses>
* sponsor: <name of sponsor>
discussions-to: <URL of current canonical discussion thread>
status: <draft | active | accepted | rejected | withdrawn>
The author header lists the names, and optionally the email addresses of
all the authors/owners of the RFC. The format of the author header values must
be:
Random J. User <random@example.com>
if the email address is included, and just:
Random J. User
if the address is not given. Most RFC authors use their real name, but if you prefer a different name and use it consistently in discussions related to the RFC, feel free to use it here.
If there are multiple authors, each should be on a separate line.
The sponsor field records which developer (core, or otherwise approved) is
sponsoring the RFC. If one of the authors of the RFC is a core developer then no
sponsor is necessary and thus this field should be left out.
The discussions-to header provides the URL to the current canonical discussion
thread for the RFC.
Draft RFCs are freely open for discussion and proposed modification, at the
discretion of the authors, until submitted to the oneAPI Construction Kit core
developers for review and resolution. Substantive content changes should
generally be first proposed on the RFC’s discussion thread listed in its
discussions-to header, while copyedits and corrections can be submitted as a
GitHub issue or GitHub pull request. RFC authors can
update the RFCs themselves by using a GitHub PR to submit their changes.
When in doubt, please check first with the RFC author and/or an RFC editor.
It occasionally becomes necessary to transfer ownership of RFCs to a new champion. In general, it is preferable to retain the original author as a co-author of the transferred RFC, but that’s really up to the original author. A good reason to transfer ownership is because the original author no longer has the time or interest in updating it or following through with the RFC process, or has fallen off the face of the ‘net (i.e. is unreachable or not responding to email). A bad reason to transfer ownership is because the author doesn’t agree with the direction of the RFC. One aim of the RFC process is to try to build consensus around a RFC, but if that’s not possible, an author can always submit a competing RFC.
If you are interested in assuming ownership of a RFC, you can also do this via pull request. Fork the repository, make your ownership modification, and submit a pull request. You should mention the original author in a comment on the pull request. (If the original author’s GitHub username is unknown, use email.) If the original author doesn’t respond in a timely manner, the RFC editors will make a unilateral decision (it’s not like such decisions can’t be reversed :).
For each new RFC that comes in an editor does the following:
.md).clang-format settings), and Markdown syntax. Editors may
correct problems themselves, but are not required to do so.If the RFC isn’t ready, an editor will send it back to the author for revision, with specific instructions. If Markdown formatting is a problem, ask the author(s) to use rfc-0002 as a template and resubmit.
Once the RFC is ready for the repository, a RFC editor will:
Updates to existing RFC should be submitted as a GitHub pull request.
Many RFCs are written and maintained by developers with write access to the oneAPI Construction Kit codebase. The RFC editors monitor the RFC repository for changes, and correct any structure, grammar, spelling, or markup mistakes they see.
RFC editors don’t pass judgment on RFCs. They merely do the administrative & editorial part (which is generally a low volume task).
This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive.