熟悉 RFC(征求意见)流程和条件后,您可能需要创建提案以供 Fuchsia Eng Council 审核。
如需创建 RFC,您需要创建一个 Gerrit 更改,其中至少包含以下三个文件:
创建元数据
RFC 的元数据定义了许多值,这些值用于为RFC 概览填充 RFC 信息。
如需标识您的 RFC,您需要修改 docs/contribute/governance/rfcs/_rfcs.yaml,以添加有关您的 RFC 的信息。
在 RFC 中,您需要提供以下信息:
参考文档
RFC 元数据 | |
---|---|
name | 必填
定义 RFC 名称。首次创建 RFC 时,您应使用 |
title | 必填
为 RFC 定义标题。此标题必须简短,并能用几个字词说明您的 RFC。 |
short_description | 必填
为您的 RFC 定义简短说明。此说明必须简短,不应超过几句话。 |
authors | 必填
创建 RFC 作者列表。
|
file | 必填
为 RFC 的 Markdown 文件定义文件名。其中应包含 RFC 的
在您收到 RFC 名称之前,请使用 |
area | 必填
列出 RFC 影响的各个方面。
有效区域 。 有效区域
|
issue | 必填
在 https://fxbug.dev/ 上定义用于跟踪 RFC 的问题列表。
如果您没有“问题”编号,可以将此值留空,
|
gerrit_change_id | 必填
包含 rfc 的 gerrit 更改的 |
submitted | 必填
以 |
status | 必填
定义 RFC 的状态。首次提交 RFC 时,此值应为 |
reviewers | 批准或拒绝后必须提供
通过 Gerrit 更改定义 RFC 的审核者。 |
consulted | 批准或拒绝后必须提供
就此 RFC 征求过意见的利益相关方,但其 +1 不是必需的。 |
reviewed | 必填
定义您收到 Fuchsia Eng Council 关于您的 RFC 是接受还是拒绝的决定的日期。 |
示例
- 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: ''
为 RFC 创建元数据后,您就可以编写包含 RFC 信息的 Markdown 文件了。
创建 Markdown 文件
填写完 RFC 元数据和 RFC 的 name
后,您可以为 RFC 创建 Markdown 文件。
如需创建 Markdown 文件,请执行以下操作:
使用 RFC 模板创建新的 Markdown 文件。此文件的命名必须基于您添加到元数据文件中的
file
值。使用文本编辑器修改文件时,您需要将模板中包含
rfcid
变量的第一行修改为 RFC 的name
。例如,如果您的name
为"RFC-NNNN"
,则第一行如下所示:{% set rfcid = "RFC-NNNN" %}
在“## 摘要”标题后面,填写 RFC 的各个部分。
填写完 Markdown 文件后,您就可以在目录中为 RFC 创建条目了。
创建 _toc.yaml 条目
为 RFC 创建元数据并创建 Markdown 文件后,您就可以在目录 (TOC) 中列出 RFC 了。
如需添加目录条目,请执行以下操作:
- 修改 //docs/contribute/governance/rfcs/_toc.yaml 文件。
- 在最后一个条目下方,按以下格式添加您的 RFC 条目。
参考文档
- title: "name: title" path: /docs/contribute/governance/rfcs/file.md
示例
- title: "RFC-0001: RFC Process"
path: /docs/contribute/governance/rfcs/0001_rfc_process.md
其中,name
、title
和 file
是您在元数据文件中定义的值。
创建目录条目后,您就可以提交 RFC 以供审核了。
将更改内容送审
修改元数据文件、创建 Markdown 文件并添加目录条目后,您就可以创建要审核的更改了。
更改的提交消息的第一行必须是 [rfc]
,后跟 RFC 的名称。提交消息正文还可以包含 RFC 的简短说明。例如:
[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.
将更改邮寄给最初的一组审核员。Fuchsia Eng Council 会自动收到有关 RFC 创建的通知。
如需详细了解如何在 Fuchsia 项目中创建更改,请参阅提交更改。
更改 RFC 提案的状态
您的更改通过审核流程后,Fuchsia 工程委员会会通知您您的提案是被接受还是被拒绝。无论提案的最终状态如何,我们都会为您分配 RFC 编号,因此请务必提交每个提案,无论最终状态如何。
收到工程委员会的最终状态后,请执行以下操作:
在 RFC 文件(
.md
扩展程序)中,修改为 RFC 分配的name
。例如,如果系统为您分配了RFC-9999
,则第一行应如下所示:{% set rfcid = "RFC-9999" %}
使用分配的 RFC 编号重命名 RFC 文件(
.md
扩展名)。例如,如果系统分配给您的文件名为RFC-9999
,请将其重命名为9999_<filename>.md
。在 //docs/contribute/governance/rfcs/_toc.yaml 中修改 RFC 的 TOC 条目,以反映 RFC 编号。例如,如果系统为您分配了
RFC-9999
,您的条目可能如下所示:- title: "RFC-9999: My RFC proposal" path: /docs/contribute/governance/rfcs/9999_<filename>.md
更新 RFC 提案的元数据。如果您已正确填写初始元数据,则只需更新 docs/contribute/governance/rfcs/_rfcs.yaml 中的以下值即可。
name
:使用分配的 RFC 名称。例如"'RFC-9999'
。file
:使用您在上面的步骤中使用的文件名。例如'9999_<filename>.md'
。status
:使用为 RFC 分配的状态,该状态可以是'Accepted'
或'Rejected'
。reviewers
:使用更改的审核员列表。例如,如果您的审核员是 abarth@google.com、cpu@google.com 和 vaas@google.com,['abarth@google.com', 'cpu@google.com', 'vaas@google.com']
。Reviewed
:请使用 RFC 获得批准或遭拒的日期(年-月-日)。例如,2020 年 3 月 15 日为'2020-03-15'
。
已接受的 RFC 提案的元数据如下所示:
- 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'
上传包含 RFC 文件更新的更改补丁。
获得批准后,请与您的协调员合作提交 RFC。具体而言,您的协调员必须将 CL 增加 2 点。
您已成功提交 RFC 提案。