blob: 33c1447a3cebc19026f497ef4bb23153f5707b64 [file] [log] [blame] [view]
# Fuchsia RFC Process
The Fuchsia RFC process has evolved from the following RFCs:
* [RFC-0001: Fuchsia Request for Comments process](0001_rfc_process.md)
* [RFC-0006: Addendum of the RFC process for Zircon](0006_addendum_to_rfc_process_for_zircon.md)
* [RFC-0067: Additions to Fuchsia RFC process](0067_rfc_process_additions.md)
* [RFC-0017: The FTP Process is dead, long live the RFC Process!](0017_folding_ftp_into_rfc.md)
* [RFC-0122: RFC Stakeholders](0122_stakeholders.md)
This page collates the above RFCs and captures the current process.
After reviewing this process, you can follow
[this guide to create an RFC][create].
[TOC]
## Summary
The Fuchsia RFC process is intended to provide a consistent and transparent path
for making project-wide, technical decisions. For example, the RFC process can
be used to evolve the project roadmap and the system architecture.
## Motivation
Currently, the Fuchsia project does not have a formal process for making
project-wide, technical decisions. At our current scale, this informality
results in different people having different, sometimes inconsistent, viewpoints
on where the project is going and how the system is put together. By
establishing a consistent and transparent path for making project-wide,
technical decisions, all the stakeholders can be confident about the technical
direction of the project.
## Design
This section describes the design of the RFC process.
### When to use the process {#when-to-use-the-process}
The RFC process can be used for any change to Fuchsia that would benefit from
its structured approach to decision making and its durable record of the
decision.
The vast majority of changes do not _require_ an RFC. Instead, these changes can
be made using the [code review
process](/docs/development/source_code/contribute_changes.md). However,
technical decisions that have broad impact across the project require broader
agreement and must be socialized with the project using the RFC process.
The following kinds of changes must use the RFC process:
* *Adding constraints on future development.* Some decisions, once made,
constrain the future development of the system. We need to be careful when
making such decisions because they can be difficult to revise later.
* *Making project policy.* Project policies have broad impact across the
system, often affecting contributors throughout the project. Examples
include: changing the set of supported languages (impacts everyone who needs
to debug and understand the system), deprecating a widely-used API, and
changing testing requirements for a broad class of code changes.
* *Changing the system architecture.* The system architecture describes how the
system fits together as a whole. Changing the system architecture, by
definition, crosses boundaries between subsystems and requires careful
consultation with many stakeholders.
* *Delegating decision-making authority.* There are often classes of decisions
that the project needs to make frequently and that benefit from specialized
expertise. Rather than making all these decisions through the RFC process,
the project can delegate decision-making authority for those classes of
decisions to another group or process. For example, we often need to make
decisions about platform APIs, which add constraints on future development,
but it would not be practical to use the RFC process for every change to the
platform API.
* *Escalations.* Finally, contentious changes can benefit from the transparency
and clarity of the RFC process. If there is a disagreement about technical
direction that cannot be resolved by an individual technical leader, the
decision can be escalated to the RFC process either by one of the disagreeing
parties or by another contributor.
In addition to the general considerations outlined above, some areas declare
additional criteria. Please consult these documents when relevant:
| Area | Criteria RFC |
|---------------------|--------------|
| Component Framework | [RFC-0098](0098_component_framework_rfc_criteria.md)
| FIDL | [RFC-0049](0049_fidl_tuning_process_evolution.md)
| Software Delivery | [RFC-0103](0103_software_delivery_rfc_criteria.md)
| Zircon | [RFC-0006](0006_addendum_to_rfc_process_for_zircon.md)
Other changes that might benefit of the RFC process are ones that require manual
or automated large scale changes of the codebase. For example how logs are
written or how error paths are handled. Rather than live with islands of
consistency, the aspiration is to find the best patterns and uniformly apply
them to the entire codebase.
### Roles and responsibilities {#roles-and-responsibilities}
People interact with the RFC process in several roles:
* *RFC Authors.* An RFC Author is a person who writes an RFC. Everyone who
contributes to Fuchsia can be an RFC Author. A given RFC can have one or more
authors. The authors of a given RFC drive the process for that RFC.
* *Eng Council.* The [Eng Council (FEC)](../eng_council.md) facilitate
discussion and make the final decision as to whether the project accepts an
RFC.
* *Facilitator.* The person appointed by FEC to shepherd this RFC through the
RFC process. Today, this person must be an FEC member.
* *Stakeholder.* A stakeholder is a person who has a stake in whether the
project accepts a given RFC. Stakeholders are typically Fuchsia contributors,
but some RFCs might have stakeholders beyond the Fuchsia project. For
example, stakeholders might be involved in other projects that use Fuchsia or
are otherwise affected by changes to Fuchsia. Stakeholders do not always
participate directly in discussions about RFCs. Instead, stakeholders are
often *represented* by someone, often a technical lead or other person
responsible for a group of stakeholders.
* *Reviewer(s).* The stakeholders whose +1 or -1 will be considered when the
FEC decides to accept or reject the RFC. (While a +2 is the "approve" on code
CLs, we tend to look to reviewers to +1 or -1 to indicate their support or
lack thereof, and look to the facilitator to +2 upon approval.)
* *Consulted.* The stakeholders whose feedback on the RFC was sought, but whose
+1 or -1 is not considered when the FEC decides to accept or reject the RFC.
### How the process works
This section describes each step involved in the RFC process.
#### Step 1: Socialize
The first step in the RFC process is to socialize your idea with the project.
For example, you might have noticed a problem that you think is important to
solve. Are other people aware of this problem? Someone else might already be
working on the problem or might have some background or context about the
problem that would be useful to you. The earlier you discover this information,
the better.
Please note that the idea does not need to be polished before starting this step.
It's best to start socializing as early as possible to receive feedback on
whether the idea is feasible and if the direction is correct. This can potentially
save the authors time and effort in case the idea does not materialize or if
the direction needs to change significantly.
While mechanically, an RFC takes shape as a markdown file reviewed using a
Gerrit code change, using a more dynamic medium than a code review during the
socialization phase, e.g. Google Doc or other, can be beneficial. Should another
medium be chosen to socialize, it is strongly encouraged to carry over the
relevant context from the more dynamic medium over to RFC writeup. For instance,
back-and-forth conversations may lead to additional "alternatives considered"
entries to be added.
Compared to the remaining steps in the process, this step is relatively
informal. This document does not contain a rigorous description of how to
socialize your idea. Socializing technical ideas is a skill unto itself.
However, a good place to start is to raise the topic in discussions with the
technical leads for areas related to the problem you are trying to solve. For
example, you might want to consult with people in the `OWNERS` files for the
areas of the codebase will need to be modified to execute your idea.
During this phase, the RFC author should start to identify the stakeholders for
this RFC.
If you are unsure how to socialize your idea, consider asking a technical leader
for advice. They will often have more experience socializing ideas and might be
able to point you in a good direction.
> *Example.* This RFC was socialized by having a discussion in the Eng Forum,
> which is a regular meeting inside Google of various engineering leaders
> involved in the project. The RFC was also socialized with the creators of the
> FTP and CTP process, who have good background and context about these
> processes.
*Exit criteria*: None specifically. This is per the author's discretion.
This step is meant to help the author crystalize the goal(s) and potential solutions.
If they feel that this is accomplished, then they can proceed to the next step.
#### Step 2: Draft {#draft}
Once you have gathered all the background and context you can through
socialization, you are ready to start the formal part of the RFC process. The
next step is to write a first draft of the RFC document itself.
Mechanically, an RFC is a markdown file in the
`//docs/contribute/governance/rfcs` directory. To create an RFC, you create a
CL that adds a file to that directory. You must start by making a copy of the
[RFC template](TEMPLATE.md). The template is designed to guide you towards
writing a high-quality RFC by prompting you to think through the problem you are
trying to solve in a semi-structured way.
Any other files that are part of the RFC, diagrams for example, can be added to
the `resources` directory under a subfolder with the same name as the RFC itself.
Example:`//docs/contribute/governance/rfcs/resources/<RFC_name>/diagram.png`.
Do not worry about assigning a number to your RFC at this stage. Instead, use
`NNNN` as a placeholder. For example, the file name should be something like
`NNNN_my_idea.md`. The RFC will get a number shortly before landing.
The RFC author should propose an initial set of stakeholders in consultation
with the experts in their RFC [area](/docs/contribute/governance/areas). The set
of stakeholders may initially be left empty or incomplete. If there is any
ambiguity, they should consult FEC for assistance identifying stakeholders.
> *Tip.* Consult the [RFC best practices doc](best_practices.md) for advice
> about drafting and iterating on your RFC.
> *Suggestion.* Consider marking the CL containing your RFC as a
> "work-in-progress" until you are ready for feedback.
The act of uploading the CL is sufficient to get a facilitator assigned to
your RFC. FEC monitors new RFC CLs as the
signal to identify the right facilitator for the new RFC.
*Exit criteria*: CL containing your RFC is created.
#### Step 3: Iterate {#iterate}
Once you have created a CL containing the first draft of your RFC, you are ready
to iterate on your idea with the appropriate stakeholders. Hopefully you will
have already discovered most the appropriate stakeholders as part of socializing
your idea, but you are very likely to discover additional stakeholders at this
stage. RFC author(s) should request from the FEC to identify all stakeholders
early in the process, thus reducing the likelihood of a surprise at the
submission step.
Mechanically, you should invite stakeholders to provide feedback on your RFC by
adding them to the "Reviewers" (for stakeholders whose +1 is required) or "CC"
fields (for "consulted" stakeholders) in the CL, as you would for a normal code
review. In addition, you may email your CL to eng-council-discuss@fuchsia.dev
soliciting additional feedback. The stakeholders should provide you feedback by
leaving comments on your RFC in the code review tool.
Anyone can propose an additional stakeholder for a given RFC, including
themselves, by commenting on the RFC CL, although these proposals may not always
be accepted. If there is broad agreement, the RFC author should add the
stakeholder. FEC may also request that the author add stakeholders.
A stakeholder may 'opt out' and ask to be removed, or may delegate their review
(for example, to another expert in the relevant area). FEC may request that a
stakeholder be removed or moved from "reviewer" to "consulted".
If the discussion is too complex for the code review tool, consider scheduling a
meeting with the relevant stakeholders to have a more efficient discussion.
After the meeting, you must post a summary of the meeting in a comment on the CL
so that people who were not at the meeting can understand what was discussed
during the meeting.
If the discussion becomes contentious, please escalate to one of the RFC
Editors. The Eng Council can help move the discussion forward, for example by
providing additional structure to the discussion or moving the discussion to
another forum. Regardless of how the discussion proceeds, the results of any
off-CL discussion must be captured in the CL, often by posting a summary of the
discussion as a CL comment.
Feedback may include comments from people who are not stakeholders. The author
should respond to these comments if relevant, but settling them is not
necessarily required to move to the last call stage. If the comments point to a
disagreement about who is a stakeholder, FEC can help resolve this.
At FEC's discretion, RFCs that would benefit from more socialization should be
scheduled for an [engineering
review](/docs/contribute/governance/eng_council.md#eng-review) meeting. Some
triggers leading to scheduling an engineering review are:
* Difficulty to identify relevant stakeholders(s). It might be the case than an
RFC receives many comments, suggestions, push back, and that the author(s)
are unclear how to act on this feedback, and which represents core feedback
which is potentially a blocker to the RFC being accepted, vs auxiliary
feedback which may be curiosity, future plans, etc.
* Difficulty for RFC author(s) and stakeholder(s) to converge on open items.
If you wish to withdraw your RFC, you can mark the CL containing the RFC as
abandoned. You, or someone else, can always resurrect your RFC later if
circumstances change. If you are resurrecting an RFC created by someone else,
you should start the RFC process over from the beginning, but you can use the
withdrawn RFC as a starting point rather than `TEMPLATE.md`. Please confer with
the original authors to determine whether they wish to continue to have their
names associated with the new incarnation of the RFC.
*Note to reviewers:* The RFC process is meant to encourage a variety of
perspectives and vibrant discussions. Often, giving negative feedback in a public
forum might be difficult. If needed, reviewers can reach out to their leads,
peers or Eng Council to help them formulate the feedback so it can be delivered
effectively in the CL.
> *Suggestion.* If you are interested in RFCs, consider configuring the Gerrit
> Code Review tool to [send you an email > notification](https://gerrit-review.googlesource.com/Documentation/user-notify.html)
> when a CL modifies the `//docs/contribute/governance/rfcs` directory.
*Exit criteria:* All stakeholders identified and approved by Eng Council; feedback
solicited and incorporated.
#### Step 4: Last call {#last-call}
Once the iterations on the RFC are converging, the author must email
eng-council@fuchsia.dev requesting them to move the RFC's status to last call.
An Eng Council member will send an email to all stakeholders and
eng-council-discuss@fuchsia.dev to solicit any final feedback before moving to
the decision step. The RFC will be open for feedback for the next 7 calendar days.
Typically, reviewers sign off with a +1 and the facilitator will sign off with a
+2. Consulted stakeholders may also sign off with a +1 or +2 if they wish to
express their enthusiasm for the RFC, although this is not required.
Stakeholders who wish to object to an RFC can set the Code-Review flag to -1 or
-2, depending on how strongly they feel that the RFC should not move forward.
When setting the Code-Review flag to -1 or -2, a stakeholder must state their
reason for objecting, ideally in a way that would let someone understand the
objection clearly without having to read the entire discussion that preceded
the objection.
A stakeholder setting the Code-Review flag to -1 or -2 does not necessarily
prevent the project from accepting the RFC. See the ["How decisions are made"
section](#how-decisions-are-made) below for more details about how the project
decides whether to accept an RFC.
After all the stakeholders have weighed in with their Code-Review flags, send an
email to eng-council@fuchsia.dev to prompt the Eng Council to decide whether to
accept your RFC.
*Exit criteria:* Feedback provided by all stakeholders; all feedback addressed.
#### Step 5: Submit
If the project decides to accept your RFC, a member of the Eng Council will
comment on your CL stating that the RFC is accepted and will assign the RFC a
number, typically the next available number in the series. If there are any -1
or -2 Code-Review flags, the Eng Council will explicitly clear each flag by
summarizing the objection and by describing why the RFC is moving forward
despite the objection. Eng Council will indicate if any additional information
needs to be documented in your RFC, such as rationale for a different approach
or tradeoffs being made.
If the project decides to reject your RFC, a member of the Eng Council will
comment on your CL stating that the RFC is rejected, provide a rationale
for the rejection and will assign the RFC a number. Rejected RFCs are valuable
engineering artifacts. The Eng Council will work with the RFC Authors to land
a version of the RFC that is marked as rejected and incorporates the rationale.
If the Eng Council identifies one or many unresolved open items, the RFC may be
moved back to the [iterate](#iterate) step. The Eng Council will ask of the
author(s) to resolve the open items identified with the relevant stakeholders
before another request to review the RFC will be granted.
You should upload a new patchset of your RFC with the assigned number, both in
the title of the RFC and in the filename. If your RFC is approved and requires
implementation, please make sure you have an issue filed in the issue tracker
and put a link to the issue in the header of your RFC.
The Eng Council will then mark your CL Code-Review +2 and you can land your RFC!
*Congratulations! You have contributed a valuable engineering artifact to the
project!*
*Exit criteria:* RFC number assigned; any applicable rationale, tradeoffs and
Eng Council feedback incorporated; RFC merged.
### How decisions are made
The decision whether to accept an RFC is made by the Eng Council, acting in
[rough consensus](https://en.wikipedia.org/wiki/Rough_consensus) with each
other. If the decision involves an RFC that has Eng Council members as authors,
those members must recuse themselves from the decision.
If the Eng Council cannot reach rough consensus, the RFC is not accepted.
In deciding whether to accept an RFC, the Eng Council will consider the
following factors:
* Does the RFC advance the goals of the project?
* Does the RFC uphold the values of the project?
* Were all of the stakeholders appropriately represented in the discussion?
* If any stakeholders objected, does the Eng Council understand the objections
fully?
Decisions made by the Eng Council can be escalated to the governing authority
for the project.
### Process to amend RFCs
An existing RFC can be amended if the following criteria are met:
* Clarifications on what was already approved.
* Mechanical amendments such as updating links, documentation, usage, etc.
* Any improvement or minor changes in design discovered later, for example,
during implementation.
For changes in design, please capture what the original design goals were, and why
and how they changed.
For any significant changes in design, please submit a new RFC.
* In the new RFC, please reference the original RFC(s) and explicitly call out the
type of change in the title, e.g., Addendum.
* If the design in the original RFC is being deprecated, amend the original RFC
to call this out and reference the new RFC.
* If there are multiple RFCs that make changes to the same area, create a new RFC
compiling the existing RFCs. Please also amend the existing RFCs to reference the new one.
If the RFC process is being updated, please also update the [RFC process page]
(rfc_process.md).
## Documentation
This RFC serves as documentation for the RFC process.
## Drawbacks, Alternatives, and Unknowns
The primary cost of implementing this proposal is that introducing a formal
decision-making process might slow down the pace of decision-making. The process
might be heavier than necessary for some kinds of decisions.
Recording decisions in the source repository has the effect of making those
decisions more difficult to change. That effect might be positive in some
scenarios, but the effect might also be negative in other scenarios.
The criteria in the ["when to use the process"
section](#when-to-use-the-process) attempts to mitigate this drawback by scoping
the process to consequential situations but such scoping is bound to have false
positives and false negatives.
There are a large number of possible alternative strategies for solving the
underlying problem. For example, we could use a decision-making process that
centers around a synchronous meeting, but such a process will have difficulty
scaling to a global open-source project. We could also have selected a different
decision-making mechanism that balanced more towards consensus or more towards
authority.
## Prior art and references
There is a good deal of prior art about decision-making processes for
open-source projects. This proposal is strongly influenced by the following
existing processes:
* *IETF RFC process.* The IETF has run a successful, large-scale
[decision-making process](https://ietf.org/standards/process/) for a long
period of time. The process described in this document draws a number of
ideas from the IETF process, including some of the terminology.
* *Rust RFC process.* The Rust community runs an [RFC
process](https://github.com/rust-lang/rfcs/blob/HEAD/text/0002-rfc-process.md),
which has been effective at making decisions for somewhat similar software
engineering project. The process described in this document is fairly
directly modelled after the Rust RFC process.
* *Blink Intent-to-implement process.* The Chromium project runs a
[decision-making process](https://www.chromium.org/blink/launching-features)
for behaviors that affect web pages. The process described in this document
is informed by my (abarth) experience helping to design and run that process
for a period of time.
* *FIDL Tuning Proposal.* The Fuchsia project has had direct experience using a
similar process [to make decisions about the FIDL
language](/docs/contribute/governance/deprecated-ftp-process.md). This
proposal exists because of the success of that decision-making process.
[swd]: /docs/contribute/governance/rfcs/0103_software_delivery_rfc_criteria.md
[create]: /docs/contribute/governance/rfcs/create_rfc.md