-
Notifications
You must be signed in to change notification settings - Fork 23
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
This RFC will be open for comment until 2024-01-19.
- Loading branch information
Showing
2 changed files
with
290 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,181 @@ | ||
# RFC template and process for OpenXLA | ||
|
||
| Status | Proposed | | ||
:-------------- |:---------------------------------------------------- | | ||
| **RFC #** | [NNN](https://github.com/openxla/community/pull/NNN) | | ||
| **Author(s)** | Jacques Pienaar (jpienaar@openxla.org) | | ||
| **Sponsor** | Thea Lamkin (thealamkin@openaxla.org) | | ||
| **Updated** | 2023-12-30 | | ||
|
||
## Objective | ||
|
||
Introducing a Request For Comments (RFC) process for proposing and discussing | ||
substantial changes. | ||
|
||
## Motivation | ||
|
||
RFCs improves visibility and enables early engagement with proposals to inform | ||
design. The process of creating RFCs inside OpenXLA project have been ad hoc. | ||
This has resulted in more effort when creating a RFC, more uncertainty as to | ||
whom reviews what, where and how (including having RFCs lag). The RFC process | ||
and template attempts to address both of these. | ||
|
||
The RFC process is not intended to replace the existing workflow of opening and | ||
reviewing pull requests. The existing PR approach is fully sufficient for many | ||
smaller changes. | ||
|
||
This process affects all developers and community members but in particular | ||
folks working cross components. | ||
|
||
## User Benefit | ||
|
||
This should both reduce uncertainty for RFC authors as well as provide a simple | ||
structure to use. For reviewers/maintainers this should reduce mental overhead | ||
by creating a consistent form. | ||
|
||
For substantially larger changes (functionality, behavior, architecture), an | ||
RFC even prior to writing any code may help with: | ||
|
||
* Gathering and integrating feedback into a proposal from other maintainers and | ||
users of the component(s). | ||
* Documenting why specific changes and decisions were made. | ||
* Building consensus among community members. | ||
|
||
## Design Proposal | ||
|
||
The RFC proposal and template will be bootstrapped based on those from TensorFlow | ||
[RFC process](https://www.tensorflow.org/community/contribute/rfc_process). We | ||
expect the process and template may evolve based on usage and community | ||
feedback. | ||
|
||
The process of creating an RFC follows as: | ||
|
||
### Submitting an RFC | ||
|
||
1. Before submitting an RFC, discuss your aims with project contributors and | ||
maintainers and get early feedback. Use the developer mailing list for the | ||
project concerned (openxla-discuss@openxla.org, or the list for the relevant | ||
component). | ||
|
||
2. Draft your RFC. | ||
|
||
* Follow the [RFC template](https://github.com/openxla/community/blob/main/rfcs/yyyymmdd-rfc-template.md). | ||
* Name your RFC file `YYYYMMDD-descriptive-name.md`, where `YYYYMMDD` is the date of submission, and `descriptive-name` relates to the title of your RFC. For instance, if your RFC is titled _Parallel Widgets API_, you might use the filename `20180531-parallel-widgets.md`. | ||
* If you have images or other auxiliary files, create a matching directory of the form `YYYYMMDD-descriptive-name` in which to store those files. | ||
|
||
After writing the RFC draft, get feedback from maintainers and contributors before submitting it. | ||
|
||
Writing implementation code is not a requirement, but it may help design discussions. | ||
|
||
3. Recruit a sponsor. | ||
|
||
* A sponsor must be a maintainer of the project. | ||
* Identify the sponsor in the RFC, before posting the PR. | ||
|
||
You _may_ post an RFC without a sponsor, but if within a month of posting the PR there is still no sponsor, it will be closed. | ||
|
||
4. Submit your RFC as a pull request to [openxla/community/rfcs](https://github.com/openxla/community/tree/main/rfcs). | ||
|
||
Include the header table and the contents of the _Objective_ section in the | ||
comment of your pull request, using Markdown. For an example, please see [this | ||
example RFC](https://github.com/openxla/community/pull/5). Include the GitHub | ||
handles of co-authors, reviewers, and sponsors. | ||
|
||
At the top of the PR identify how long the comment period will be. This | ||
should be a _minimum of two weeks_ from posting the PR. | ||
|
||
5. Email the developer mailing list with a brief description, a link to the PR | ||
and a request for review. | ||
|
||
6. The sponsor will request a maintainer review meeting, no sooner than two | ||
weeks after the RFC PR is posted. If discussion is lively, wait until it has | ||
settled before going to review. The goal of the review meeting is to resolve | ||
minor issues; consensus should be reached on major issues beforehand. | ||
|
||
7. The meeting may approve the RFC, reject it, or require changes before it | ||
can be considered again. Approved RFCs will be merged into | ||
[community/rfcs](https://github.com/openxla/community/tree/main/rfcs), and | ||
rejected RFCs will have their PRs closed. | ||
|
||
### RFC participants | ||
|
||
Many people are involved in the RFC process: | ||
|
||
* **RFC author** — one or more community members who write an RFC and are | ||
committed to championing it through the process. | ||
* **RFC sponsor** — a maintainer who sponsors the RFC and will shepherd it | ||
through the RFC review process. | ||
* **review committee** — a group of module maintainers who have the | ||
responsibility of recommending the adoption of the RFC (in rare cases, core | ||
maintainers would also serve this role). | ||
* Any **community member** may help by providing feedback on whether the RFC | ||
will meet their needs. | ||
|
||
A sponsor is a project maintainer responsible for ensuring the best possible | ||
outcome of the RFC process. This includes: | ||
|
||
* Advocating for the proposed design. | ||
* Guiding the RFC to adhere to existing design and style conventions. | ||
* Guiding the review committee to come to a productive consensus. | ||
* If changes are requested by the review committee, ensure these are made and | ||
seek subsequent approval from the committee members. | ||
* If the RFC moves to implementation: | ||
- Ensuring proposed implementation adheres to the design. | ||
- Coordinate with appropriate parties to successfully land implementation. | ||
|
||
### Community members and the RFC process | ||
|
||
The purpose of RFCs is to ensure the community is well represented and served | ||
by new changes to OpenXLA. It is the responsibility of community members to | ||
participate in reviewing RFCs where they have an interest in the outcome. | ||
|
||
Community members who are interested in an RFC should: | ||
|
||
* **Provide feedback** as soon as possible to allow adequate time for consideration. | ||
* **Read RFCs** thoroughly before providing feedback. | ||
* Be **civil and constructive**. | ||
|
||
### Alternatives Considered | ||
|
||
We considered different prior art and processes, in particular from LLVM, TFX | ||
and Swift evolution, but chose the most familiar to existing folks involved | ||
with expectation that it may evolve with community. | ||
|
||
### Performance Implications | ||
|
||
N/A. | ||
|
||
### Dependencies | ||
|
||
N/A. | ||
|
||
### Engineering Impact | ||
|
||
N/A. | ||
|
||
### Platforms and Environments | ||
|
||
N/A. | ||
|
||
### Best Practices | ||
|
||
This RFC does not introduce the bar for when a change is deemed substantial. As | ||
a rough guide a change is [substantial](https://mozac.org/rfc/0001-rfc-process) if it | ||
|
||
* Affects multiple components; | ||
* Affects how components interact through either their public or internal APIs; | ||
* Fndamentally changes how a component is implemented, how it manages state or reacts to changes, in a way that isn’t self-explanatory or a direct result of a bug fix. | ||
|
||
### Tutorials and Examples | ||
|
||
While this RFC itself serves as an example of the RFC process, there are many other | ||
[TensorFlow RFCs](https://github.com/tensorflow/community/tree/master/rfcs) to consult. | ||
|
||
### Compatibility | ||
|
||
N/A. | ||
|
||
### User Impact | ||
|
||
N/A. | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,109 @@ | ||
# Title of RFC | ||
|
||
| Status | (Proposed / Accepted / Implemented / Obsolete) | | ||
:-------------- |:---------------------------------------------------- | | ||
| **RFC #** | [NNN](https://github.com/openxla/community/pull/NNN) (update when you have community PR #)| | ||
| **Author(s)** | My Name (me@example.org), AN Other (you@example.org) | | ||
| **Sponsor** | A N Expert (whomever@openxla.org) | | ||
| **Updated** | YYYY-MM-DD | | ||
| **Obsoletes** | RFC it replaces, else remove this header | | ||
|
||
## Objective | ||
|
||
What are we doing and why? What problem will this solve? What are the goals and | ||
non-goals? This is your executive summary; keep it short, elaborate below. | ||
|
||
## Motivation | ||
|
||
Why this is a valuable problem to solve? What background information is needed | ||
to show how this design addresses the problem? | ||
|
||
Which users are affected by the problem? Why is it a problem? What data supports | ||
this? What related work exists? | ||
|
||
## User Benefit | ||
|
||
How will users (or other contributors) benefit from this work? What would be the | ||
headline in the release notes or blog post? | ||
|
||
## Design Proposal | ||
|
||
This is the meat of the document, where you explain your proposal. If you have | ||
multiple alternatives, be sure to use sub-sections for better separation of the | ||
idea, and list pros/cons to each approach. If there are alternatives that you | ||
have eliminated, you should also list those here, and explain why you believe | ||
your chosen approach is superior. | ||
|
||
Make sure you’ve thought through and addressed the following sections. If a | ||
section is not relevant to your specific proposal, please explain why, e.g., | ||
your RFC addresses a convention or process, not an API. | ||
|
||
|
||
### Alternatives Considered | ||
|
||
* Make sure to discuss the relative merits of alternatives to your proposal. | ||
|
||
### Performance Implications | ||
|
||
* Do you expect any (speed / memory)? How will you confirm? | ||
* There should be microbenchmarks. Are there? | ||
* There should be end-to-end tests and benchmarks. If there are not (since this | ||
is still a design), how will you track that these will be created? | ||
|
||
### Dependencies | ||
|
||
* Dependencies: does this proposal add any new dependencies to OpenXLA? | ||
* Dependent projects: are there other areas of OpenXLA or things that use | ||
OpenXLA (JAX, etc.) that this affects? How have you identified these | ||
dependencies and are you sure they are complete? If there are dependencies, | ||
how are you managing those changes? | ||
|
||
### Engineering Impact | ||
|
||
* Do you expect changes to binary size / startup time / build time / test times? | ||
* Who will maintain this code? Is this code in its own buildable unit? Can this | ||
code be tested in its own? Is visibility suitably restricted to only a small | ||
API surface for others to use? | ||
|
||
### Platforms and Environments | ||
|
||
* Platforms: does this work on all platforms supported by OpenXLA? If not, why | ||
is that ok? Will it work on embedded/mobile? Does it impact automatic code | ||
generation or mobile stripping tooling? Will it work with transformation | ||
tools? | ||
* Execution environments (Cloud services, accelerator hardware): what impact do | ||
you expect and how will you confirm? | ||
|
||
### Best Practices | ||
|
||
* Does this proposal change best practices for some aspect of using/developing | ||
OpenXLA? How will these changes be communicated/enforced? | ||
|
||
### Tutorials and Examples | ||
|
||
* If design changes existing API or creates new ones, the design owner should | ||
create end-to-end examples which reflects how new feature will be used. Some | ||
things to consider related to the tutorial: | ||
- This should be written as if it is documentation of the new feature, | ||
i.e., consumable by a user, not a OpenXLA developer. | ||
- The code does not need to work (since the feature is not implemented yet) | ||
but the expectation is that the code does work before the feature can be | ||
merged. | ||
|
||
### Compatibility | ||
|
||
* Does the design affect compatibility requirements? (e.g., [StableHLO](https://github.com/openxla/stablehlo/blob/main/rfcs/20220912-compatibility.md) or JAX ones). | ||
|
||
### User Impact | ||
|
||
* What are the user-facing changes? How will this feature be rolled out? | ||
|
||
## Detailed Design | ||
|
||
This section is optional. Elaborate on details if they’re important to | ||
understanding the design, but would make it hard to read the proposal section | ||
above. | ||
|
||
## Questions and Discussion Topics | ||
|
||
Seed this with open questions you require feedback on from the RFC process. |