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
• Create a markdown file
• Create a _toc.yaml entry

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:

- 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.

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

- 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.

The first line of your change's commit message must be [rfc], followed by the RFC's name. The body of the commit message may also include your RFC's short description. For example:

[rfc] zx_channel_iovec_t support for zx_channel_write and zx_channel_call

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.

Mail your change to your initial set of reviewers. The Fuchsia Eng Council will be automatically notified about the RFC's creation.

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, March 15th 2020 would be '2020-03-15'.

   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-31'
   

5. Upload a patch to your change with the updates to the RFC files.

6. Once approved, work with your facilitator to submit your RFC. Specifically, your facilitator must +2 the CL.

You have successfully submitted an RFC proposal.