概览
本文档介绍了 Fuchsia API Council，这个组织负责确保 Fuchsia API Surface 的质量和长期健康状况。该委员会将与创建和修改 Fuchsia 的 API 的人员进行建设性协作，帮助指导这些 API 的发展。委员会将明确传达其决定（包括基本理由），并通过贡献 Fuchsia 的 API 可读性评分准则来记录最佳实践。
定义
Fuchsia 系统接口是 Fuchsia 操作系统提供给系统上运行的软件的二进制接口。例如，vDSO 的入口点以及系统使用的所有 FIDL 协议都是 Fuchsia 系统接口的一部分。
客户端库是一个库，为 Fuchsia 编写软件的人员可能会选择使用它，而不是直接与 Fuchsia 系统接口进行交互。例如，FDIO 是一个客户端库，可为 Fuchsia 系统接口中的底层 fuchsia.io 协议提供类似于 POSIX 的抽象。
Fuchsia IDK 是 Fuchsia 项目向为 Fuchsia 编写软件的人员提供的库、元数据和工具的集合。其中，Fuchsia IDK 包含 Fuchsia 系统接口的定义以及许多客户端库。
Fuchsia API Surface 是我们在 IDK 中包含的工件的集合。这包括但不限于 Fuchsia 系统接口、Fuchsia IDK 中包含的客户端库、IDK 元数据以及核心 Fuchsia 开发者工具。
Fuchsia 贡献者是指参与创建 Fuchsia 操作系统的人员，包括为 Google 工作的人员和不为 Google 工作的人员。
Fuchsia API 设计人员是创建或修改 Fuchsia API Surface 的人员，包括为 Google 工作的人员和非工作者。
最终开发者是指编写可使用 Fuchsia API Surface 的软件的人员。
用户是指使用运行 Fuchsia 操作系统的设备的用户。
目标
Fuchsia API Council 的最终目标是围绕 Fuchsia 操作系统建立健康的软件生态系统。维护健康的生态系统需要平衡许多问题，包括发展生态系统和引导生态系统实现特定结果。
值
这个生态系统有许多参与者，他们扮演着不同的角色。理想情况下，我们能够设计出可同时满足生态系统中所有成员需求的 API，但 API 设计人员经常需要做出需要权衡的决策。委员会应帮助 API 设计者在做出这些决策时遵循以下选区优先级：
- 用户
- 最终开发者
- 创作贡献者
- API 设计人员
- 委员会成员
例如，我们设计的 API 应该能够保护用户隐私，即使代价是无法满足最终开发者的所有需求。同样，我们应该设计更适合最终开发者的 API，即使这些设计会给实现 API 的人员带来更高的负担。
这些价值有助于引导生态系统满足用户需求，从长远来看，这有利于促进生态系统的健康与发展，因为用户更有可能加入并保留在满足其需求的生态系统中。
策略
为实现这些目标，该委员会重点关注以下指标：
功能。该委员会负责 Fuchsia API Surface 的功能。具体而言，功能是指 API 是否满足生态系统参与者的需求。例如，委员会应负责以下事项：我们的 API 在多大程度上保护用户的隐私、我们的 API 在多大程度上帮助最终开发者完成特定任务，以及我们的 API 能否帮助 Fuchsia 贡献者不断改进其实现。
易用性。委员会负责 Fuchsia API Surface 的易用性。例如，委员会应力争在我们的 API 中表达类似概念的方式保持一致，以便最终开发者更轻松地学习我们的 API。同样，该委员会应确保我们的 API 有详尽的文档记录，并且从其声明来看，接口的语义直观明了。
对系统的影响。委员会对因使用 Fuchsia API Surface（包括预期和意外使用）对整个系统造成的负担负责。例如，使用轮询的 API 会给系统带来很大的负担，因为它们需要客户端持续运行以监控条件的变化。评估系统影响需要大量的判断和经验，尤其是要预测 API 的意外使用。
沟通清晰。委员会有责任清晰地传达这些决定以及这些决定背后的理由。这种沟通应让决策过程公开透明，并有助于 API 设计人员了解如何创建高质量的 API。例如，委员会应通过贡献 Fuchsia 的 API 可读性评分准则来记录最佳实践。
客户满意度。该委员会负责与 API 设计人员展开有建设性的协作。委员会应营造一种环境，让委员会成员和 API 设计人员齐心协力改善 Fuchsia API Surface。API 设计人员应将此委员会视为提供积极价值，帮助他们打造更好的 API，而不是官式的负担。例如，委员会成员应及时、尊重地对 API 审核请求作出回复。
成员资格状态
该委员会由在以下方面证明出色的 Fuchsia 贡献者组成：
无论是在 Fuchsia 内部，还是过去与其他平台合作期间，对 API 的质量和长期运行状况有着良好的判断。
对 API 设计人员（即协作者）而言，拥有出色的沟通和协作能力。
成员由项目的每个职能领域任命。
该委员会由 Fuchsia Eng Council 监管。
委员会有一把主席，由 Fuchsia 领导层任命，并推动 Fuchsia Eng 委员会的运作。主席具有以下职责：
- 安排会议。
- 设置每场会议的日程。
- 评估委员会是否已达成粗略共识。
功能领域
| 领域 | 主要 | 次要 |
|---|---|---|
| 蓝牙 | jamuraa@google.com | silberst@google.com |
| 组件框架 | geb@google.com | ypomortsev@google.com |
| 开发者 | wilkinsonclay@google.com | chaselatta@google.com |
| 诊断 | crjohns@google.com | miguelfrde@google.com |
| 驱动程序 | cja@google.com | jocelyndang@google.com |
| 驱动程序 SDK | jocelyndang@google.com | cja@google.com |
| 体验 | chaselatta@google.com | ianloic@google.com |
| FIDL | ianloic@google.com | 无。 |
| 固件 | dpursell@google.com | 无。 |
| 外部 ABI 兼容性 | lindkvist@google.com | qsr@google.com |
| 图形 | jbauman@google.com | dalesat@google.com |
| HCI | quiche@google.com | neelsa@google.com |
| 身份 | 无。 | |
| 内核 | cpu@google.com | abarth@google.com |
| 媒体 | dalesat@google.com | 无。 |
| 指标 | camrdale@google.com | 无。 |
| Netstack | brunodalbo@google.com | 无。 |
| 电源 | mbrunson@google.com | 无。 |
| 产品组装 | aaronwood@google.com | awolter@google.com |
| 安全性 | 无。 | |
| 会话 | ypomortsev@google.com | 无。 |
| 软件交付 | kevinwells@google.com | etryzelaar@google.com |
| 存储空间 | csuter@google.com | 无。 |
| 测试 | crjohns@google.com | 无。 |
| 工具链 | mcgrathr@google.com | 无。 |
| 视图系统 | neelsa@google.com | quiche@google.com |
| 虚拟化 | 无。 | |
| Web | wez@google.com | ianloic@google.com |
| WLAN | silberst@google.com | jamuraa@google.com |
随着项目不断发展，职能领域列表（因而委员会的组成）也会不断变化。职能领域列表由 Fuchsia 领导层维护。
在考虑添加某个区域时，委员会会考虑以下因素：
- 覆盖范围。该区域是否已经被其他某个区域涵盖，或者是否有任何差异？
- 作用域。此工作区域面积是否足以安排专人安排？
- 持续的需求。以前是否有必要这样做？
决策流程
如果委员会需要作出决定，则决策流程如下。相关地区的委员会成员是主要决策者，但整个委员会是最终决策者。委员会整体根据主席评估的粗略共识做出决定。
主要决策者可以推迟决定，在这种情况下，由委员会做出决定。如果委员会未能达成粗略共识，将由主席做出最终决定。
委员会成员可以要求委员会推翻主要决策者。如果委员会未能达成粗略共识，则主要决策者的决定将保持有效。
Operations
该委员会有两个主要职能：API 审查和 API 校准。
API 审核
对 Fuchsia API Surface 的每项更改都需要获得委员会成员的批准。对特定职能领域的更改通常应获得负责该领域的委员会成员的批准，但如果负责的委员会成员不在办公室，任何委员会成员都可以批准该更改。
在合并之前，除了常规的 Code-Review+2 之外，修改 Fuchsia API Surface 的每项更改都必须收到来自 api-council@fuchsia.dev 成员的 API-Review+1。对于某项更改，同一人可以同时提供 API-Review+1 和 Code-Review+2。如需查看有关此 Gerrit 功能的文档，请参阅查看标签。API 委员会的成员不能提供自己的 CL 的 API-Review+1，除非这些更改很小且没有争议（例如，文档更改）。即便如此，我们仍鼓励第二位委员会成员进行独立审核。
对于细微的 API 更改，尤其是对现有 API 的增量优化，代码审核通常足以让 API 审核人员给出更改 API-Review+1。不过，对于较大的变更，尤其是那些会大幅扩展 API 接口的变更，API 设计人员应编写一个 RFC（请参阅 Fuchsia RFC 模板），说明该 API 的设计，包括用例和示例，以及安全性和隐私权注意事项。如果 API 审核者认为只通过代码审核来批准更改，那么 API 审核者可以随时请求 API 设计者撰写 RFC，即使对于细微更改也是如此。
若要将 API 纳入 Fuchsia SDK 中，API 必须清除两个障碍：必须有一个准备就绪且愿意的客户，并且 API 必须经过 API 校准。
此外，我们还建议 API 设计人员向委员会成员寻求早期反馈。 例如，API 设计人员应考虑与委员会成员共享仍在进行中的 API 设计文档，以便在设计过程的早期阶段获得意见。委员会成员应参与这些讨论，目标是与 API 设计师合作，帮助设计出最佳 API。API 设计人员还可以在设计过程的早期向全体委员会征求反馈意见，方法是请主席在即将举行的 API 校准会议的日程中留出一个名额（请参阅下一部分）。
API 审核人员应与 API 设计人员合作，对 API RFC 进行改进，使 API 审核人员能够放心批准文档。获批的文件可作为相关 API 的记录计划。但是，修改 API Surface 的各个 CL 在合并之前仍需审核 API-Review+1。API 设计人员应当知道，遵循获得批准的 API RFC 中列出的方案的 CL 应该能够非常轻松地审核 API-Review+1，即使是来自其他委员会成员的也是如此。
API 设计人员或审核人员可以将 API RFC 转给整个委员会，请主席在即将举行的 API 校准会议的日程中留出一个名额（请参阅下一部分）。例如，如果 API 审核人员认为相关文档没有得到充分校准、该 API 特别复杂或重要，或者审核人员因截止日期即将到来或其他团队感到压力，API 审核人员可能会向整个委员会转介文档。
API 校准
API 委员会会定期召开 API 校准会议。API 校准的目的是提高整个项目的 API 审核一致性，并通过交叉探索整个委员会的最佳实践来提高 API 审核的质量。这些会议通常设有一位主持人，他负责确保会议不偏离主题，并帮助确保每位参与者都有机会提供反馈。
Fuchsia 贡献者可以观察 API 校准会议。观察这些会议是了解有关改进 API 接口的最佳实践。
查看包含 API 变更的 RFC
在某些情况下，API 变更可能需要通过 RFC 讨论建议的变更。API 校准的首要任务是审核已上报给整个委员会的所有 RFC。如果有多份待处理文件，则主席会选择委员会处理这些文件的顺序。
编写文档的 API 设计人员应展示文档，为委员会提供必要的背景信息，帮助委员会了解其中涉及的问题。 之后，推荐文档的人员应讨论他们需要反馈的 API 设计领域。我们鼓励委员会成员集中针对这些方面提供反馈，但也可以针对文档整体提供反馈。
查看积压
Fuchsia API Surface 包含大量在委员会成立之前设计的 API。委员会将处理积压的 API 审核，最终达到 Fuchsia API Surface 中的每个 API 均已审核的阶段。理想情况下，在 Fuchsia 承诺其 API 的向后兼容性之前，委员会将有机会审核整个 Fuchsia API Surface。
主席选择委员会处理积压作业的顺序，试图在审核项目不同领域的 API 与审核累积大量客户的 API 的紧迫性之间取得平衡。
审核 API 时，负责该 API 相关领域的委员会成员（以下称“负责的成员”）将呈现该 API，并向该委员会提供必要的背景信息，以了解该 API 的使用场景和动机。负责成员可以邀请一位或多位主题专家帮助提供额外的背景信息和技术详情。理想情况下，负责的成员已预先审核了 API，并且会有一个建议的修改列表。
次要审核
委员会还将循环检查项目的功能领域，对自上个周期以来每个领域的 API Surface 所做的更改进行二次审核。通过此活动，委员会可以向成员提供有关其近期 API 审核的反馈。
主席将选择审核领域的顺序，力求在审核来自项目不同领域的 API 与审核进行大量更改的 API 的紧迫性之间取得平衡。
在二次审核过程中，担任 API 更改主要审核者的委员会成员将呈现更改以及任何相关的 API 设计文档，为委员会提供必要的背景信息，以了解更改的使用场景和动机。我们也鼓励（但不要求）做出相关更改的 API 设计人员参与。
通常，委员会应尊重在主要 API 审核期间所做的决定，但建议委员会成员提供反馈，说明 API 可以如何改进，从而使未来的审核有益。根据 API 的成熟度，主要审核人员可能会决定将这些改进整合到 API 中。在极少数情况下，委员会可以根据委员会的决策流程推翻主要审核者。
致谢
本文档主要参考了 Android API 委员会、Web API 所有者、W3C 和 IETF 使用的治理结构。特别感谢 Jeff Brown、Dimitri Glazkov、Jeremy Manson、Rebecca Silberstein 和 Greg Simon 分享他们在 API 治理方面的经验以及他们对本文档初稿的深思熟虑的反馈。