概览
本文档介绍了 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 员工和非 Google 员工。
最终开发者是指编写使用 Fuchsia API Surface 的软件的人员。
用户是指使用搭载 Fuchsia 操作系统的设备的人员。
目标
Fuchsia API 委员会的最终目标是围绕 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 的意外用途。
沟通清晰度。该委员会负责向 Fuchsia 贡献者明确传达决策以及这些决策背后的原因。这种沟通应使决策过程透明化，并帮助 API 设计师了解如何创建高质量的 API。例如，该委员会应通过为 Fuchsia 的 API 可读性评分标准做出贡献来记录最佳实践。
客户满意度。该委员会负责与 API 设计师进行富有成效的协作。该委员会应营造一个环境，让委员会成员和 API 设计师能够携手合作，改进 Fuchsia API Surface。API 设计者应将该委员会视为提供积极价值的组织，帮助他们打造更好的 API，而不是一个官僚主义的负担。例如，委员会成员应以尊重的方式及时回复 API 审核请求。
成员资格状态
该委员会由 Fuchsia 贡献者组成，他们已证明自己：
能够对 Fuchsia 中的 API 或过去在其他平台上使用的 API 的质量和长期运行状况做出正确判断。
具备出色的沟通能力和协作能力（API 设计师 [即其协作者] 的视角）。
成员由项目的每个功能领域任命。
该委员会由 Fuchsia Eng Council 监督。
该委员会有一名主席，由 Fuchsia 领导层任命，负责协助 Fuchsia Eng 委员会的运作。主席有以下职责：
- 安排会议。
- 设置每次会议的议程。
- 评估委员会是否达成了大致共识。
职能领域
| 领域 | 主要 | 次要 |
|---|---|---|
| 蓝牙 | jamuraa@google.com | silberst@google.com |
| 组件框架 | geb@google.com | dgilhooley@google.com |
| 开发者 | wilkinsonclay@google.com | chaselatta@google.com |
| 诊断 | crjohns@google.com | miguelfrde@google.com |
| 驱动程序 | cja@google.com | jocelyndang@google.com |
| Driver SDK | jocelyndang@google.com | surajmalhotra@google.com |
| 体验 | chaselatta@google.com | ianloic@google.com |
| FIDL | ianloic@google.com | 无 |
| 固件 | dpursell@google.com | 无 |
| 外部 ABI 兼容性 | lindkvist@google.com | qsr@google.com |
| 图形 | costan@google.com | emircan@google.com |
| HCI | neelsa@google.com | emircan@google.com |
| 身份 | 无 | 无 |
| 内核 | cpu@google.com | abarth@google.com |
| 媒体 | dalesat@google.com | ypomortsev@google.com |
| 指标 | frousseau@google.com | 无 |
| Netstack | brunodalbo@google.com | 无 |
| 电源 | mbrunson@google.com | prashanthsw@google.com |
| 产品组装 | aaronwood@google.com | awolter@google.com |
| 安全 | 无 | 无 |
| 会话 | quiche@google.com | neelsa@google.com |
| 软件交付 | galbanum@google.com | etryzelaar@google.com |
| 存储 | csuter@google.com | 无 |
| 测试 | anmittal@google.com | crjohns@google.com |
| 工具链 | mcgrathr@google.com | phosek@google.com |
| 查看系统 | emircan@google.com | neelsa@google.com |
| 虚拟化 | 无 | 无 |
| 网站 | 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 设计人员编写 RFC，即使对于小更改也是如此，如果 API 审核人员不愿仅通过代码审核来批准更改。
要想纳入 Fuchsia SDK，API 必须跨越两个障碍：必须有准备就绪且愿意使用的客户，并且 API 必须已通过 API 校准。
我们还鼓励 API 设计者向委员会成员寻求早期反馈。例如，API 设计者应考虑与委员会成员分享正在进行的 API 设计文档，以便在设计流程的早期获取反馈。委员会成员应参与这些讨论，目的是与 API 设计师合作，帮助设计出最佳 API。API 设计者还可以在设计流程的早期向全体委员会寻求反馈，方法是向主席申请在即将举行的 API 校准会议的日程安排中预留一个时间空档（请参阅下一部分）。
API 审核人员应与 API 设计人员合作，改进 API RFC，直到 API 审核人员认为可以批准该文档为止。已获批准的文档可用作相关 API 的记录方案。不过，修改 API 接口的各个 CL 仍需先通过 API-Review+1 审核，然后才能合并。API 设计者应预期，遵循已获批准 API RFC 中所述计划的 CL 应该能够非常轻松地审核 API-Review+1，即使是来自其他委员会成员的审核也是如此。
API 设计者或审核者可以向主席申请在即将举行的 API 校准会议的议程中预留时间，以便将 API RFC 提交给整个委员会（请参阅下一部分）。例如，如果 API 审核员认为自己没有足够的经验，如果 API 特别复杂或重要，或者如果审核员感到迫于即将到期的截止日期或其他团队的压力，则可能会将文档转交给整个委员会。
API 校准
API 委员会会定期召开会议进行 API 校准。API 校准旨在促进整个项目中的 API 评价保持一致，并通过跨委员会交叉使用最佳实践来提高 API 评价的质量。这类会议通常有一名主持人，负责确保会议不偏离主题，并帮助确保每位参与者都有机会提供反馈。
Fuchsia 贡献者可以旁听 API 校准会议。观看这些会议是了解有关改进 API Surface 的最佳实践的好方法。
查看包含 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 OWNERS、W3C 和 IETF 使用的治理结构。特别感谢 Jeff Brown、Dimitri Glazkov、Jeremy Manson、Rebecca Silberstein 和 Greg Simon 分享了他们在 API 治理方面的经验，并对本文档的早期草稿提供了深思熟虑的反馈。