Creating an RFC

Once you are familiarized with the RFC (request for comments) process and criteria, you may want to create a proposal for the Fuchsia Eng Council to review.

To create an RFC, you need to create a Gerrit change that contains at least the following three files:

Create metadata

The metadata of an RFC defines many values that are used to populate the RFC information for the RFC overview.

To identify your RFC, you need to edit the docs/contribute/governance/rfcs/_rfcs.yaml to include information about your RFC.

For your RFC, you need to include the following information:

Reference

RFC metadata
nameRequired

Define an RFC name. When you first create an RFC, you should use RFC-NNNN. After your RFC is approved or rejected, the Fuchsia Eng Council assigns you a unique name to use.

titleRequired

Define a title for your RFC. This title must be short and explain your RFC in a few words.

short_descriptionRequired

Define a short description for your RFC. This description must be short and should not be longer than a few sentences.

authorsRequired

Create a list of the authors for the RFC.

  • For a single author, use this format ["myemail@example.com"].
  • For multiple authors, use this format ["myemail@example.com", ...]
fileRequired

Define the filename for the markdown file of your RFC. This should include the numerical part of the name of your RFC and an identifier based on the RFC title.

Until you receive an RFC name, use NNNN for the numerical part, for example, NNNN_file. Once your RFC is reviewed you will receive an RFC name. For example, you could use a file of 0001_rfc_process.md for an RFC with an id of 0001 and a title of Fuchsia Request for Comments (RFC) process.

areaRequired

Define a list of the areas that your RFC affects.

  • For a single area, use this format `['area']`.
  • For multiple areas, use this format `['area1', ...]`.

Valid areas

Valid areas
  • Bluetooth
  • Build
  • Component Framework
  • Developer
  • Devices
  • Diagnostics
  • Driver SDK
  • Drivers
  • Experiences
  • FIDL
  • Firmware
  • General
  • Governance
  • Graphics
  • HCI
  • Identity
  • Kernel
  • Media
  • Metrics
  • Netstack
  • PosixCompat
  • Power
  • Recovery
  • Security
  • Sessions
  • Software Delivery
  • Storage
  • System
  • Testing
  • Toolchain
  • View System
  • Virtualization
  • Web
  • WLAN
issueRequired

Define a list of the issue that tracks your RFC on https://fxbug.dev/. In case you don't have an `issue` number, you can leave this value blank, [].

  • For a single issue, use this format ['issue'].
  • For multiple issues, use this format ['issue1', ...]
gerrit_change_idRequired

The id of your gerrit change that contains your rfc. These are the final digits of the URL of your gerrit change. For example, if the URL of your change is https://fuchsia-review.googlesource.com/c/fuchsia/+/366393, use a gerrit_change_id of 366393.

submittedRequired

Define the date when you first created the change for your RFC in a year-month-day format.

statusRequired

Define the status of your RFC. When you first submit an RFC, this value should be blank. After your RFC is reviewed, the status will be changed to Accepted or Rejected.

reviewersRequired once approved or rejected

Define the reviewers of the RFC from the Gerrit change.

consultedRequired once approved or rejected

Stakeholders who were consulted about this RFC, but whose +1 is not required.

reviewedRequired

Define the date when you received the decision from the Fuchsia Eng Council as to if your RFC is accepted or rejected.

Sample

- name: 'RFC-NNNN'
  title: 'zx_channel_iovec_t support for zx_channel_write and zx_channel_call'
  short_description: 'This RFC introduces a new mode to zx_channel_write and zx_channel_call that copies input data from multiple memory regions rather than from a single contiguous buffer.'
  authors: ['bprosnitz@google.com']
  file: '0010_channel_iovec.md'
  area: ['Zircon']
  issue: ['60623']
  gerrit_change_id: ['433621']
  status: ''
  reviewers: []
  submitted: '2020-09-25'
  reviewed: ''

Once you have created the metadata for your RFC, you are ready to write a markdown file with the information for your RFC.

Create a markdown file

Once you have filled out your RFC metadata and a name for your RFC, you can create a markdown file for your RFC.

To create a markdown file:

  1. Create a new markdown file from the RFC template. This file must be named based on the file value that you added to the metadata file.

  2. When you edit the file with a text editor, you need to edit the first line of the template that contains a rfcid variable with the name of your RFC. For example, if your name is "RFC-NNNN", the first line looks like the following:

    
    {% set rfcid = "RFC-NNNN" %}
    
    
  3. Fill out the different sections for your RFC, after the ## Summary header.

Once you have finished filling out the markdown file, you are ready to create an entry for the RFC in the table of contents.

Create a _toc.yaml entry

Once you have created the metadata for your RFC and created the markdown file, you are ready to list your RFC in the TOC (table of contents).

To add a TOC entry:

  1. Edit the //docs/contribute/governance/rfcs/_toc.yaml file.
  2. Add your RFC entry below the last entry in the following format.

Reference

   - title: "name: title"
     path: /docs/contribute/governance/rfcs/file.md

Sample

- title: "RFC-0001: RFC Process"
  path: /docs/contribute/governance/rfcs/0001_rfc_process.md

Where name, title, and file are the values that you defined in the metadata file.

Once you have created a TOC entry, you are now ready to submit your RFC for review.

Send a change for review

Once you have edited the metadata file, created a markdown file, and added a TOC entry, you are ready to create a change for review.

You can add the current Fuchsia Eng Council as reviewers:

For more information, on creating a change in the Fuchsia project, see Contribute changes.

Change the status of an RFC proposal

Once your change has gone through the review process, the Fuchsia Eng Council will let you know if your proposal was accepted or rejected. Regardless of the final status of the proposal, you will be assigned an RFC number and it is important to submit each proposal regardless of the final status.

After you receive a final status from the Eng Council, do the following:

  1. In your RFC file (.md extension), edit the assigned name for your RFC. For example, if you were assigned RFC-9999, the first line should look like the following:

    
    {% set rfcid = "RFC-9999" %}
    
    
  2. Rename your RFC file (.md extension) with the assigned RFC number. For example, if you were assigned RFC-9999, rename your file to 9999_<filename>.md.

  3. Edit the TOC entry for your RFC in //docs/contribute/governance/rfcs/_toc.yaml to reflect the RFC number. For example, if you were assigned RFC-9999, your entry may look like the following:

    - title: "RFC-9999: My RFC proposal"
      path: /docs/contribute/governance/rfcs/9999_<filename>.md
    
  4. Update the metadata for your RFC proposal. If you correctly filled out the initial metadata, you only need to update the following values in docs/contribute/governance/rfcs/_rfcs.yaml.

    • name: Use the RFC name that was assigned. For example, "'RFC-9999'.
    • file: Use the filename that you used in the steps above. For example, '9999_<filename>.md'.
    • status: Use the status that was assigned to your RFC which can be 'Accepted' or 'Rejected'.
    • reviewers: Use the list of reviewers from your change. For example, if your reviewers were abarth@google.com, cpu@google.com, and vaas@google.com, ['abarth@google.com', 'cpu@google.com', 'vaas@google.com'].
    • Reviewed: Use the date (year-month-day) on which your RFC was approved or rejected. For example, November 11th 2020 would be '2020-11-11'.

    The metadata for an accepted RFC proposal looks like the following:

    - name: 'RFC-0010'
      title: 'zx_channel_iovec_t support for zx_channel_write and zx_channel_call'
      short_description: 'This RFC introduces a new mode to zx_channel_write and zx_channel_call that copies input data from multiple memory regions rather than from a single contiguous buffer.'
      authors: ['bprosnitz@google.com']
      file: '0010_channel_iovec.md'
      area: ['Zircon']
      issue: ['60623']
      gerrit_change_id: ['433621']
      status: 'Accepted'
      reviewers: ['cpu@google.com', 'kulakowski@google.com', 'abarth@google.com', 'pascallouis@google.com']
      submitted: '2020-09-25'
      reviewed: '2020-10-06'
    
  5. Upload a patch to your change with the updates to the RFC files.

  6. Once approved, submit your RFC.

You have successfully submitted an RFC proposal.