{# Imports JSONs to generate content #}

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

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:

Note: You may have additional files if you are including images in your RFC.

Create metadata
Create a markdown file
Create a _toc.yaml entry

Note: You can use the fx rfc tool that automates these three steps. This tool helps you to interactively populate the required RFC metadata fields and creates a blank RFC markdown file using the template.

Create metadata {#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
`name`	Required 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.
`title`	Required Define a title for your RFC. This title must be short and explain your RFC in a few words.
`short_description`	Required Define a short description for your RFC. This description must be short and should not be longer than a few sentences.
`authors`	Required 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", ...]
`file`	Required 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`.
`area`	Required 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 Note: If you think there should be additional areas, suggest a new RFC area. Valid areas {% for area in areas %} `{{ area }}` {% endfor %}
`issue`	Required Define a list of the issue that tracks your RFC on {{ issue_url }}. 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_id`	Required 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`.
`submitted`	Required Define the date when you first created the change for your RFC in a `year-month-day` format.
`status`	Required Define the status of your RFC. When you first submit an RFC, this value should be `Pending`. After your RFC is reviewed, the status will be changed to `Accepted` or `Rejected`.
`reviewers`	Required once approved or rejected Define the reviewers of the RFC from the Gerrit change.
`consulted`	Required once approved or rejected Stakeholders who were consulted about this RFC, but whose +1 is not required.
`reviewed`	Required 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 {#create-markdown}

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:

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.
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:
```
{% verbatim %}
{% set rfcid = "RFC-NNNN" %}
{% endverbatim %}
```
Fill out the different sections for your RFC, after the ## Summary header.

Note: If you are adding images, you should name the images based on the file name of your RFC. For example, file-fig_1.png.

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 {#toc}

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

Note: For more information about _toc.yaml files, see Updating site navigation and TOC files.

To add a TOC entry:

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

Reference

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

Sample

- title: "RFC-0001: RFC Process"
  path: /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 {#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.

Note: After you submit your change, update the metadata to include the assigned Gerrit change id and submit a patch to your change.

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

Change the status of an RFC proposal {#rfc-change-status}

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:

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:
```
{% verbatim %}
{% set rfcid = "RFC-9999" %}
{% endverbatim %}
```
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.
Edit the TOC entry for your RFC in //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: /contribute/governance/rfcs/9999_<filename>.md
```
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'
```
Upload a patch to your change with the updates to the RFC files.

Note: For more information on creating a patch, see Create and upload a patch.
Once approved, submit your RFC.

You have successfully submitted an RFC proposal.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

create_rfc.md

create_rfc.md

Creating an RFC

Create metadata {#create-metadata}

Reference

Sample

Create a markdown file {#create-markdown}

Create a _toc.yaml entry {#toc}

Reference

Sample

Send a change for review {#review}

Change the status of an RFC proposal {#rfc-change-status}

Files

create_rfc.md

Latest commit

History

create_rfc.md

File metadata and controls

Creating an RFC

Create metadata {#create-metadata}

Reference

Sample

Create a markdown file {#create-markdown}

Create a _toc.yaml entry {#toc}

Reference

Sample

Send a change for review {#review}

Change the status of an RFC proposal {#rfc-change-status}