Fuchsia

{% include “docs/contribute/governance/rfcs/_common/_rfc_header.md” %}

RFC best practices

This document provides guidelines for how authors and reviewers can get the most out of the RFC process.

Think of RFCs as design docs

The RFC process is how the Fuchsia project makes decisions. Some RFCs contain decisions to adopt some policy across the project. For example, RFC-0004 specifies that storage sizes should be given in IEC notation (e.g., KiB, not KB). When that RFC was accepted, it meant that we as a project decided to follow that policy. These policy-setting RFCs are relatively rare, though.

The majority of RFCs are essentially design docs. When a design doc RFC is accepted, it means that we as a project decided to solve a problem in a certain way. An accepted RFC is a historical document, recording the fact that everyone who had a stake in that design was comfortable moving forward with it.

Focus on getting buy-in

When writing an RFC (or anything, for that matter), ask yourself: “why am I writing this?”

Presumably you‘re writing an RFC because you want to change something, but you think your change could have an impact on other members of the project. Before moving forward, you want to make sure they know what you’re planning to do, and that they don‘t mind. These folks who might be impacted by your change are your stakeholders. Once they +1 your RFC and it gets accepted, you’ll have a written record that they're happy with your change. Proceed with confidence!

Let this goal guide the contents of your RFC:

  • Emphasize the aspects of your design that need stakeholder buy-in. For example, the interfaces your stakeholders use are more important than the implementation.
  • Spell out the design‘s implications. If your stakeholders need to work hard to understand how the design affects them, the review will be slow, and there’s a greater chance of one of them coming to you during implementation saying, “this isn't what I agreed to!”
  • Be clear about what you‘re proposing. For example, your RFC might include commitments about how a design will work, as well as illustrative examples of how it could work. It might provide context by describing the system as it is, as well as requirements for how the system will be when implementation is done. Make it easy for your stakeholders to tell which is which. You don’t want your stakeholders to see a suggestion where you meant to give a requirement.

Include the right details

Your RFC does not need to specify every detail of your design. In fact, too much detail can make it harder for your stakeholders to understand the design‘s essential trade-offs. On the other hand, if you don’t include enough detail, different readers might come to different conclusions about what your RFC means. Finding the right level of detail is an art.

Your RFC should include all the details that have a material impact on your design's acceptability, and no more. This will be just enough detail for the stakeholders to endorse your design and for future readers to understand why it was approved. Incidental details just make the RFC harder to review.

Some RFCs get more and more detailed during review. This can be frustrating for authors and stakeholders alike. When a stakeholder asks a question about (or objects to) some part of your design, your instinct may be to add more details as clarification or justification. Before you do, consider whether removing detail would be more appropriate. If the bit they commented on doesn't make a material difference to the RFC, you can short-cut a lot of discussion by deleting it or making it more general and abstract.

To help decide whether some detail has a material impact on your design, consider these questions:

  • If you changed this detail, would anyone ever change their vote from +1 to a -1 because of it?
  • If this detail was implemented differently from what was written, would that be okay? Would your stakeholders want to be informed about the change?
  • Is it important that you decide on this detail now? Would it be better to let the implementers and their code reviewers make the call?

Keep future readers in mind

The stakeholders are your RFC‘s primary audience, but you shouldn’t forget about future readers trying understand your design after it has been accepted. Here are some tips for making your RFC accessible to a broader audience:

  • Pretend that your stakeholders are first hearing about your design via your RFC. Include (or link to documentation with) enough background to put your RFC in context.
  • Pretend that the stakeholders are only hearing about your design via the RFC. You and your stakeholders will probably discuss the RFC via email, chat, meetings, or at the very least code review comments. Future readers won't have easy access to these conversations, so make sure the text of the RFC includes any important conclusions you came to out-of-band.
  • Use stable links. Your RFC will become much harder to understand if the “background information” links dramatically change or become 404. Whenever possible, link to a specific revision of a document so future readers see the same page you see.

Don't use RFCs as documentation

Once accepted, your RFC documents the fact that your stakeholders were happy with the feature you designed. However, it shouldn't be used as documentation for the feature itself.

RFCs and documentation simply have different goals:

  • Documentation needs to be constantly updated as the system changes, but RFCs shouldn‘t change once they’re accepted (beyond minor amendments).
  • RFCs justify to the stakeholders why the design is sound and preferable to the alternatives, which probably isn't very helpful for users.
  • Documentation gives precise, procedural examples for how to use the feature, which requires a level of detail that isn't very helpful for stakeholders.

Don't link to an RFC in code or documentation to explain how a feature works. Give the feature its own documentation and link to that instead.

Some suggestions for where to put this kind of documentation:

  • Use detailed doc comments to add documentation about a specific API or code module.
  • Create a //src/my_subsystem/docs/ subdirectory in fuchsia.git. Documentation hosted in fuchsia.git can be rendered by Gitiles and is great for providing conceptual guides to your subsystem.
  • Add your documentation to fuchsia.dev if it will be useful to the wider Fuchsia community.

On the other hand, RFCs may link to documentation. In fact, if your RFC contains lots of background information, consider moving that background into documentation and linking to it instead!

Update these best practices

If you have suggestions for best practices (or you think some of the ones above could use updating) reach out to eng-council@fuchsia.dev or send a change to the FEC!