The Fuchsia RFC process has evolved from the following RFCs:
This page collates the above RFCs and captures the current process.
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.
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.
This section describes the design of the RFC process.
The vast majority of changes to Fuchsia do not require an RFC. Instead, these changes can be made using the code review process. 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:
Changing the project roadmap. The project roadmap describes changes that have broad impact across the system, often touching a large fraction of the system or crossing boundaries between subsystems.
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. For example, changing the set of supported languages impacts everyone who needs to debug and understand the system, even if not everyone uses the new language.
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, Zircon changes in the source directories:
that meet the following criteria must use RFC process:
Adding or removing Zircon system interfaces. The syscall interface, associated structures and constants is the ground truth for the entire system and has broad impact beyond Zircon itself and needs broad consensus before implementation.
Changing resource handling behaviors. How the system handles partitioning or virtualizing resources such as memory, I/O, processor time or energy consumption and what it does when they are oversubscribed or scarce.
Modifying isolation guarantees. How and what is private and isolated among equal tasks and what privileged tasks can observe and modify. Changes here need to be approved via this process in consultation with the security team.
Significant changes of performance or memory use. Sometimes when additional security, monitoring or features are added, there is a corresponding decrease in performance or higher memory use that need to be vetted via this process.
Favoring a single platform. Zircon strives to have an equal baseline of features and services across all supported architectures and boards. Changes that leverage one platform capabilities but are not feasible or practical on other supported platforms need to use this process.
Adding or Downgrading support for a platform. Adding new boards or architectures, or deprecating/reducing support for an existing platform needs to be vetted via this process.
New build configurations. Adding new build configurations increases the development and testing burden across the entire project and needs to be vetted beforehand.
Significant increases on the dependency graph. Zircon dependencies affect the entire project and significant changes, for example a new dependency on a package that itself has significant dependencies or that is large by itself, should use the RFC process.
In addition to the general considerations outlined above, FIDL changes that meet the following criteria must use RFC process:
The solution space is large, i.e. the change is one of many possibly good other solutions and there is a difficult design tradeoff to make;
The change has a large impact, i.e. The change modifies the behavior of FIDL in a substantial way such that it may introduce risk to many-or-all users of FIDL;
The change has a large scope, i.e. The change touches enough pieces of FIDL such that careful attention is required to determine whether it may or may not have a large impact.
For instance, changes to the following FIDL areas will likely require an RFC:
Additional details are provided in RFC-0049: FIDL Tuning Process Evolution.
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.
The RFC process may also be used for other kinds of changes that would benefit from its structured approach to decision making and its durable record of the decision.
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.
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.
Eng Council. The Eng Council (FEC) facilitate discussion and make the final decision as to whether the project accepts an RFC.
This section describes each step involved in the RFC process.
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.
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.
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 and RFC, you create a CL that adds a file to that directory. You must start by making a copy of the RFC template. 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.
Suggestion. Consider marking the CL containing your RFC as a “work-in-progress” until you are ready for feedback.
Exit criteria: CL containing your RFC is created.
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” or “CC” fields 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.
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.
At FEC's discretion, RFCs that would benefit from more socialization should be scheduled for an engineering review meeting. Some triggers leading to scheduling an engineering review are:
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 when a CL modifies the
//docs/contribute/governance/rfcsdirectory.
Exit criteria: All stakeholders identified and approved by Eng Council; feedback solicited and incorporated.
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, stakeholders who need to approve a CL (i.e., whose sign-off is required for the RFC to move forward) should sign-off with a +2 whereas stakeholders whose approval is not required should sign-off with a +1, but all stakeholders are welcome to sign-off with a +2 if they wish to express their enthusiasm for the RFC.
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 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.
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 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.
The decision whether to accept an RFC is made by the Eng Council, acting in 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:
Decisions made by the Eng Council can be escalated to the governing authority for the project.
An existing RFC can be amended if the following criteria are met:
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.
If the RFC process is being updated, please also update the [RFC process page] (rfc_process.md).
This RFC serves as documentation for the RFC process.
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 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.
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 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, 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 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. This proposal exists because of the success of that decision-making process.
