Skip to content

Commit 3af752d

Browse files
jpienaarjpienaar
committed
RFC for RFC process
This RFC will be open for comment until 2024-01-19.
1 parent d68f24c commit 3af752d

File tree

2 files changed

+290
-0
lines changed

2 files changed

+290
-0
lines changed

‎rfcs/20231231-rfc-format.md

+181
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
1+
# RFC template and process for OpenXLA
2+
3+
| Status | Proposed |
4+
:-------------- |:---------------------------------------------------- |
5+
| **RFC #** | [NNN](https://github.com/openxla/community/pull/NNN) |
6+
| **Author(s)** | Jacques Pienaar ([email protected]) |
7+
| **Sponsor** | Thea Lamkin ([email protected]) |
8+
| **Updated** | 2023-12-30 |
9+
10+
## Objective
11+
12+
Introducing a Request For Comments (RFC) process for proposing and discussing
13+
substantial changes.
14+
15+
## Motivation
16+
17+
RFCs improves visibility and enables early engagement with proposals to inform
18+
design. The process of creating RFCs inside OpenXLA project have been ad hoc.
19+
This has resulted in more effort when creating a RFC, more uncertainty as to
20+
whom reviews what, where and how (including having RFCs lag). The RFC process
21+
and template attempts to address both of these.
22+
23+
The RFC process is not intended to replace the existing workflow of opening and
24+
reviewing pull requests. The existing PR approach is fully sufficient for many
25+
smaller changes.
26+
27+
This process affects all developers and community members but in particular
28+
folks working cross components.
29+
30+
## User Benefit
31+
32+
This should both reduce uncertainty for RFC authors as well as provide a simple
33+
structure to use. For reviewers/maintainers this should reduce mental overhead
34+
by creating a consistent form.
35+
36+
For substantially larger changes (functionality, behavior, architecture), an
37+
RFC even prior to writing any code may help with:
38+
39+
* Gathering and integrating feedback into a proposal from other maintainers and
40+
users of the component(s).
41+
* Documenting why specific changes and decisions were made.
42+
* Building consensus among community members.
43+
44+
## Design Proposal
45+
46+
The RFC proposal and template will be bootstrapped based on those from TensorFlow
47+
[RFC process](https://www.tensorflow.org/community/contribute/rfc_process). We
48+
expect the process and template may evolve based on usage and community
49+
feedback.
50+
51+
The process of creating an RFC follows as:
52+
53+
### Submitting an RFC
54+
55+
1. Before submitting an RFC, discuss your aims with project contributors and
56+
maintainers and get early feedback. Use the developer mailing list for the
57+
project concerned ([email protected], or the list for the relevant
58+
component).
59+
60+
2. Draft your RFC.
61+
62+
* Follow the [RFC template](https://github.com/openxla/community/blob/main/rfcs/yyyymmdd-rfc-template.md).
63+
* 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`.
64+
* If you have images or other auxiliary files, create a matching directory of the form `YYYYMMDD-descriptive-name` in which to store those files.
65+
66+
After writing the RFC draft, get feedback from maintainers and contributors before submitting it.
67+
68+
Writing implementation code is not a requirement, but it may help design discussions.
69+
70+
3. Recruit a sponsor.
71+
72+
* A sponsor must be a maintainer of the project.
73+
* Identify the sponsor in the RFC, before posting the PR.
74+
75+
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.
76+
77+
4. Submit your RFC as a pull request to [openxla/community/rfcs](https://github.com/openxla/community/tree/main/rfcs).
78+
79+
Include the header table and the contents of the _Objective_ section in the
80+
comment of your pull request, using Markdown. For an example, please see [this
81+
example RFC](https://github.com/openxla/community/pull/5). Include the GitHub
82+
handles of co-authors, reviewers, and sponsors.
83+
84+
At the top of the PR identify how long the comment period will be. This
85+
should be a _minimum of two weeks_ from posting the PR.
86+
87+
5. Email the developer mailing list with a brief description, a link to the PR
88+
and a request for review.
89+
90+
6. The sponsor will request a maintainer review meeting, no sooner than two
91+
weeks after the RFC PR is posted. If discussion is lively, wait until it has
92+
settled before going to review. The goal of the review meeting is to resolve
93+
minor issues; consensus should be reached on major issues beforehand.
94+
95+
7. The meeting may approve the RFC, reject it, or require changes before it
96+
can be considered again. Approved RFCs will be merged into
97+
[community/rfcs](https://github.com/openxla/community/tree/main/rfcs), and
98+
rejected RFCs will have their PRs closed.
99+
100+
### RFC participants
101+
102+
Many people are involved in the RFC process:
103+
104+
* **RFC author** — one or more community members who write an RFC and are
105+
committed to championing it through the process.
106+
* **RFC sponsor** — a maintainer who sponsors the RFC and will shepherd it
107+
through the RFC review process.
108+
* **review committee** — a group of module maintainers who have the
109+
responsibility of recommending the adoption of the RFC (in rare cases, core
110+
maintainers would also serve this role).
111+
* Any **community member** may help by providing feedback on whether the RFC
112+
will meet their needs.
113+
114+
A sponsor is a project maintainer responsible for ensuring the best possible
115+
outcome of the RFC process. This includes:
116+
117+
* Advocating for the proposed design.
118+
* Guiding the RFC to adhere to existing design and style conventions.
119+
* Guiding the review committee to come to a productive consensus.
120+
* If changes are requested by the review committee, ensure these are made and
121+
seek subsequent approval from the committee members.
122+
* If the RFC moves to implementation:
123+
- Ensuring proposed implementation adheres to the design.
124+
- Coordinate with appropriate parties to successfully land implementation.
125+
126+
### Community members and the RFC process
127+
128+
The purpose of RFCs is to ensure the community is well represented and served
129+
by new changes to OpenXLA. It is the responsibility of community members to
130+
participate in reviewing RFCs where they have an interest in the outcome.
131+
132+
Community members who are interested in an RFC should:
133+
134+
* **Provide feedback** as soon as possible to allow adequate time for consideration.
135+
* **Read RFCs** thoroughly before providing feedback.
136+
* Be **civil and constructive**.
137+
138+
### Alternatives Considered
139+
140+
We considered different prior art and processes, in particular from LLVM, TFX
141+
and Swift evolution, but chose the most familiar to existing folks involved
142+
with expectation that it may evolve with community.
143+
144+
### Performance Implications
145+
146+
N/A.
147+
148+
### Dependencies
149+
150+
N/A.
151+
152+
### Engineering Impact
153+
154+
N/A.
155+
156+
### Platforms and Environments
157+
158+
N/A.
159+
160+
### Best Practices
161+
162+
This RFC does not introduce the bar for when a change is deemed substantial. As
163+
a rough guide a change is [substantial](https://mozac.org/rfc/0001-rfc-process) if it
164+
165+
* Affects multiple components;
166+
* Affects how components interact through either their public or internal APIs;
167+
* 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.
168+
169+
### Tutorials and Examples
170+
171+
While this RFC itself serves as an example of the RFC process, there are many other
172+
[TensorFlow RFCs](https://github.com/tensorflow/community/tree/master/rfcs) to consult.
173+
174+
### Compatibility
175+
176+
N/A.
177+
178+
### User Impact
179+
180+
N/A.
181+

‎rfcs/yyyymmdd-rfc-template.md

+109
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
# Title of RFC
2+
3+
| Status | (Proposed / Accepted / Implemented / Obsolete) |
4+
:-------------- |:---------------------------------------------------- |
5+
| **RFC #** | [NNN](https://github.com/openxla/community/pull/NNN) (update when you have community PR #)|
6+
| **Author(s)** | My Name ([email protected]), AN Other ([email protected]) |
7+
| **Sponsor** | A N Expert ([email protected]) |
8+
| **Updated** | YYYY-MM-DD |
9+
| **Obsoletes** | RFC it replaces, else remove this header |
10+
11+
## Objective
12+
13+
What are we doing and why? What problem will this solve? What are the goals and
14+
non-goals? This is your executive summary; keep it short, elaborate below.
15+
16+
## Motivation
17+
18+
Why this is a valuable problem to solve? What background information is needed
19+
to show how this design addresses the problem?
20+
21+
Which users are affected by the problem? Why is it a problem? What data supports
22+
this? What related work exists?
23+
24+
## User Benefit
25+
26+
How will users (or other contributors) benefit from this work? What would be the
27+
headline in the release notes or blog post?
28+
29+
## Design Proposal
30+
31+
This is the meat of the document, where you explain your proposal. If you have
32+
multiple alternatives, be sure to use sub-sections for better separation of the
33+
idea, and list pros/cons to each approach. If there are alternatives that you
34+
have eliminated, you should also list those here, and explain why you believe
35+
your chosen approach is superior.
36+
37+
Make sure you’ve thought through and addressed the following sections. If a
38+
section is not relevant to your specific proposal, please explain why, e.g.,
39+
your RFC addresses a convention or process, not an API.
40+
41+
42+
### Alternatives Considered
43+
44+
* Make sure to discuss the relative merits of alternatives to your proposal.
45+
46+
### Performance Implications
47+
48+
* Do you expect any (speed / memory)? How will you confirm?
49+
* There should be microbenchmarks. Are there?
50+
* There should be end-to-end tests and benchmarks. If there are not (since this
51+
is still a design), how will you track that these will be created?
52+
53+
### Dependencies
54+
55+
* Dependencies: does this proposal add any new dependencies to OpenXLA?
56+
* Dependent projects: are there other areas of OpenXLA or things that use
57+
OpenXLA (JAX, etc.) that this affects? How have you identified these
58+
dependencies and are you sure they are complete? If there are dependencies,
59+
how are you managing those changes?
60+
61+
### Engineering Impact
62+
63+
* Do you expect changes to binary size / startup time / build time / test times?
64+
* Who will maintain this code? Is this code in its own buildable unit? Can this
65+
code be tested in its own? Is visibility suitably restricted to only a small
66+
API surface for others to use?
67+
68+
### Platforms and Environments
69+
70+
* Platforms: does this work on all platforms supported by OpenXLA? If not, why
71+
is that ok? Will it work on embedded/mobile? Does it impact automatic code
72+
generation or mobile stripping tooling? Will it work with transformation
73+
tools?
74+
* Execution environments (Cloud services, accelerator hardware): what impact do
75+
you expect and how will you confirm?
76+
77+
### Best Practices
78+
79+
* Does this proposal change best practices for some aspect of using/developing
80+
OpenXLA? How will these changes be communicated/enforced?
81+
82+
### Tutorials and Examples
83+
84+
* If design changes existing API or creates new ones, the design owner should
85+
create end-to-end examples which reflects how new feature will be used. Some
86+
things to consider related to the tutorial:
87+
- This should be written as if it is documentation of the new feature,
88+
i.e., consumable by a user, not a OpenXLA developer.
89+
- The code does not need to work (since the feature is not implemented yet)
90+
but the expectation is that the code does work before the feature can be
91+
merged.
92+
93+
### Compatibility
94+
95+
* Does the design affect compatibility requirements? (e.g., [StableHLO](https://github.com/openxla/stablehlo/blob/main/rfcs/20220912-compatibility.md) or JAX ones).
96+
97+
### User Impact
98+
99+
* What are the user-facing changes? How will this feature be rolled out?
100+
101+
## Detailed Design
102+
103+
This section is optional. Elaborate on details if they’re important to
104+
understanding the design, but would make it hard to read the proposal section
105+
above.
106+
107+
## Questions and Discussion Topics
108+
109+
Seed this with open questions you require feedback on from the RFC process.

0 commit comments

Comments
 (0)