{# Imports JSONs to generate content #}
{% include “docs/contribute/governance/rfcs/_common/_rfc_header.md” %}
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.
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.
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.
Once you have created the metadata for your RFC, you are ready to write a markdown file with the information for your RFC.
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.
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:
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.
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.
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 //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
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.