Learn about the Fuchsia RFC Process (https://fuchsia.dev/fuchsia-src/contribute/governance/rfcs/rfc_process): what it is, when it should be used, how it works, and how to make the best of it.

1. Fuchsia RFCs
A blueprint for technical decision making.
pascallouis@ on behalf of FEC | May 6th
2021

2. “A consistent and transparent path for making project-wide,
technical decisions.”
= design docs +
open-source friendly workflow +
authority for approval to be direction setting
In short, RFCs is Fuchsia’s legislative branch when it comes
to technical decisions.
What are RFCs

3. Avoid information silos, all parts of Fuchsia abiding by the same
methodology for technical decision making.
Clarifies how technical decisions are made, provides a designated
group of technical leaders to turn to if blocked.
Helps all have access to the rationale and thought process behind
technical decisions. Builds a detailed corpus of knowledge which
can be back-referenced.
Quality control mechanism, ensuring any Fuchsia-wide technical
decision is vetted appropriately before proceeding.
Why do we have RFCs

4. “Technical decisions that have broad impact across the
project require broader agreement and must be socialized
with the project using the RFC process.”
i.e. any Fuchsia-wide technical decision goes through the
RFC process. When in doubt, you likely want to do an RFC.
Read more about when to use the process, or ask on
eng-council-discuss@fuchsia.dev.
RFCs levels the playing field

5. Defining “broad impact”
- General criteria RFC-0001
- Localized criteria Zircon (RFC-0006) and FIDL (RFC-0049)
"Each area is encouraged to submit additional criteria for
when an RFC should be followed for their respective area. If
criteria for an area exists, the FEC will ensure that
appropriate stakeholders are looped in." – RFC-0017
When to use the process

6. Process
Socialize Draft Iterate Last Call
Accepted
Rejected
Withdrawn
submit
https://fuchsia.dev/fuchsia-src/contribute/governance/rfcs/rfc_process

7. You have an idea? Talk with your peers about it, test your
idea against what other may think, learn how to best
describe it, related topics, previous approaches, etvc.
(This is an informal step in comparison to the rest of the
process.)
Process: 1. Socialize

8. Mechanically, draft your RFC by copying the template, and submit a
CL.
Start a thread on eng-council-discuss@fuchsia.dev announcing your
RFC.
An FEC member will be appointed to your RFC and serve as a PoC going
forward. (The FEC member will announce themselves to you.)
Process: 2. Draft

9. (That’s where the bulk of the work is.)
- Identify stakeholders;
- Have your RFC reviewed;
- Address comments, e.g. improve your write up, adapt your design,
or both;
- Rinse, repeat.
Once things have converged, you should ask to move to last call by
responding to the eng-council-discuss@fuchsia.dev thread.
Process: 3. Iterate

10. Who are the stakeholders?
- FEC can help, if needed, we can work with you to identify them.
Process: 3. Iterate

11. What if things do not converge?
- Take a step back, is there agreement on the problem statement?
- Is there agreement about the solution statement? If not, can you
articulate the points of contention?
- Find a faster medium than Gerrit to discuss, get people
together.
- Are dissenters stakeholders, or onlookers? Only stakeholders’
votes matter during ratification.
- FEC can help, if requested, we can organize a design review for
your RFC.
Process: 3. Iterate

12. Have things converged?
- Maybe you’re unsure whether you have sufficiently converged,
e.g. you have a -1 or open threads, but feel the person is not a
stakeholder.
- FEC can help, we can help provide focus to the design
conversation, and identify key objections.
- Ideally get to a point where there are no more open comment
threads and stakeholders have +1 or -1 the CL.
Process: 3. Iterate

13. Once conversation has converged (stakeholders looped in and +1’ed,
no more open threads) request the RFC to be put in last call.
The FEC appointee will review the RFC, and move it to last call.
An update on the eng-council-discuss@fuchsia.dev thread will be
posted.
Last call period is a minimum of 7 days to balances the author(s)
desire for velocity with the stakeholder(s) desire for time to
review the document. (Stakeholders can request more time if needed.)
Process: 4. Last call

14. After the 7 days waiting period, your RFC will be reviewed by
FEC. Three possible outcomes:
- Accepted → Update CL with #, merge. Now, get back to work.
- Rejected → Author a rejection rationale to be finalized with
FEC appointee, update CL with #, merge. Rejection rationale
tends to be very valuable for future designs to build upon.
- Back to Iterate. Do not pass go. Do not collect $200.
Process: 5. Submission

15. Any questions before we continue?

16. - It’s a decision making tool, results in a clear yes/no.
- Resolve technical debates decidedly. The written medium
is less forgiving about ambiguity.
- Can avoid investing too much in a direction that isn’t
aligned with the overall project-wide technical
direction.
Leverage RFCs to your advantage

17. - Helps to build the technical foundation of an area.
- Tool to capture crisp rationale for choices, trade offs,
analysis.
- Can be the basis to generalize design principles.
- Also a quality control mechanism for Fuchsia.
So also, do it because you have to.
Leverage RFCs to your advantage

18. Avoid the Waterfall
- Don’t fall in the trap of writing a whole long RFC on theorics,
that is unlikely to get ratified.
- We don’t believe in waterfall, and the RFC process is not an excuse
for good ‘ol iterate to success.
- Good RFCs will come from detailed understanding of the domain,
likely after having worked in that domain, and experienced the
issues first-hand
- An RFC should happen at the point in time where you have enough
understanding of the road ahead to write it in stone (well,
malleable git-repo backed stone).
- The “before RFC” is likely prototypes, or experimental
implementations. The “after RFC” is taking your solution to
production.

19. “Unlike cooking, for example, where largely edible, if raw,
ingredients are assembled, cut, heated, and otherwise
manipulated into something both digestible and palatable,
writing is closer to having to reverse-engineer a meal out
of rotten food.”
— David Rakoff
Shitty First Draft

20. - Start a draft! Google Doc is great, write pseudo Markdown
to make it easier to convert later.
- Seek early reviews, discuss your draft with others.
Refine.
- Work to have some alignment on the RFC within your team,
or if you are purposefully proposing something against
strongly held opinions simply say so and explain.
Gotta start somewhere, somehow

21. - Once you’ve got a draft you’re happy with, convert
quickly to Markdown and create a CL.
- We want to have conversations out in the open, where all
can get the context.
- If there were interesting conversations leading up to the
CL, capture them as best you can (e.g. ask people to
copy-paste their questions).
- Avoid iterating ad nauseum prior to a CL. The process of
convergence is interesting, and bringing all along helps.
Convert to a CL

22. Focus on the arc, the story of your design.
Start with the setting. Assume the reader has little context.
What are we trying to solve, and why are we not achieving this right now?
Give a real-life example. From there, generalize to state the problem
statement.
How are you going to solve this? Focus on each detail of your solution, and
how it contributes to the whole.
Contrast and compare. What other ways are there to solve this problem, and why
are you not pursuing them?
Good RFCs are great stories

23. Be your own editor
Spend the time to edit down, shorter crisper better.
Use real-life concrete examples, it’s easier to follow than abstract ones.
Provide as many links as possible, it exemplifies how one decision builds on
another, builds on another.
Sometimes, you’ll want to define terms and provide background before the core
text. Like here, here, or there.
Ask for help, lots of people are happy to read and review early drafts. Or listen
to the master Ira Glass on storytelling part 1, pt 2, pt 3, pt 4.

24. Good examples
- RFC-0040: Identifier uniqueness
- RFC-0064: Box<Knox>
- RFC-0077: zx_clock_update accuracy improvement
- RFC-0083: FIDL versioning
- RFC-0085: Reducing the zx_status_t space

25. It pays to get comfortable writing Markdown. It’s sure
simpler than C++, but good Markdown isn’t trivial either.
- fuchsia.dev uses Hoedown, though an easier to read spec
is the CommonMark Spec. There’s also the original spec.
- Use a rewrapping plugging for your IDE, e.g. Rewrap for
VSCode
- Live Markdown editor
https://jbt.github.io/markdown-editor/ (Github flavor)
- There’s a Fuchsia specific Markdown linter in the works.
Markdown

26. Woah, writing an RFC looks like so much work!
“Weeks of coding can save you hours of planning.”
We are building a platform. Fuchsia-wide decisions have
large ramifications. Our areas are highly interrelated, one
decision here impacts something else there.
Explicit coordination and alignment is the way to build the
best platform.
Velocity of decision making increases with clear precedent,
and clear guiding principles. RFCs help achieve both.

27. ● eng-council-discuss@fuchsia.dev (discuss)
● eng-council@fuchsia.dev (FEC only)
● Fuchsia RFC Process
● Creating an RFC
● RFC Template