概览
本文档介绍了 Fuchsia API 委员会，该委员会由一组负责 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 贡献者组成，这些贡献者已证明：
对 API 的质量和长期健康状况有良好的判断力，无论是在 Fuchsia 中还是在他们过去与其他平台合作时。
具有强大的沟通和协作能力，这是 API 设计者（即他们的协作者）所认可的。
成员由项目的每个功能区任命。
委员会由 Fuchsia 工程委员会 监督。
委员会有一位 主席，由 Fuchsia 领导层任命， 负责协调 Fuchsia 工程委员会的运作。主席的职责如下：
- 安排会议。
- 为每次会议设置议程。
- 评估委员会是否已达成大致共识。
功能区
| 领域 | 主要 | 次要 |
|---|---|---|
| 蓝牙 | jamuraa@google.com | silberst@google.com |
| 组件框架 | cgonyeo@google.com | quiche@google.com |
| 开发者 | wilkinsonclay@google.com | chaselatta@google.com |
| 诊断 | crjohns@google.com | 无 |
| Driver SDK | jocelyndang@google.com | surajmalhotra@google.com |
| 驱动程序 | cja@google.com | puneetha@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 |
| 身份 | 无 | 无 |
| 内核 | mcgrathr@google.com | rashaeqbal@google.com |
| 媒体 | dalesat@google.com | 无 |
| 指标 | frousseau@google.com | 无 |
| Netstack | brunodalbo@google.com | martinjeffrey@google.com |
| 电源 | mbrunson@google.com | prashanthsw@google.com |
| 产品组装 | aaronwood@google.com | awolter@google.com |
| 安全 | 无 | 无 |
| 软件交付 | galbanum@google.com | etryzelaar@google.com |
| 存储 | csuter@google.com | jfsulliv@google.com |
| 测试 | crjohns@google.com | 无 |
| 工具链 | mcgrathr@google.com | phosek@google.com |
| 界面 | emircan@google.com | carolineliu@google.com |
| 虚拟化 | 无 | 无 |
| 网络 | wez@google.com | ianloic@google.com |
| WLAN | mnck@google.com | silberst@google.com |
随着项目的发展，功能区列表（以及委员会的组成）也会随之发展。功能区列表由 Fuchsia 领导层维护。
在考虑添加某个区域时，委员会会考虑以下因素：
- 覆盖范围。此区域是否已由其他区域之一覆盖，还是存在差距？
- 范围。此区域是否足够大，需要专门任命一名成员？
- 持续需求。之前是否出现过将此区域作为单独区域的需求？
决策过程
如果委员会需要做出决策，决策过程如下。相关区域的委员会成员是 主要决策 者 ，但委员会整体是 最终决策者 。委员会整体通过 大致共识 做出决策，由主席评估。
主要决策者可以 推迟 决策，在这种情况下，委员会将做出决策。如果委员会未能达成大致共识，主席将做出最终决策。
委员会成员可以要求委员会 否决 主要决策者的决定。如果委员会未能达成大致共识，主要决策者做出的决定将保持不变。
运营
委员会有两个主要职能：API 审核和 API 校准。
API 审核
对 Fuchsia API Surface 的每项更改都需要获得委员会成员的批准。 特定功能区的更改通常应由负责该区域的委员会成员批准，但如果负责的委员会成员无法批准，任何委员会成员都可以批准该更改。
在合并之前，每项修改 Fuchsia API Surface 的更改都必须 从 api-council@fuchsia.dev 的成员处获得 API-Review+1，以及通常的 代码审核 +2。同一个人可以为给定的更改提供 API-Review+1 和代码审核 +2。如需了解有关 此 Gerrit 功能的文档，请参阅审核标签。API 委员会的成员不能为自己的 CL 提供 API-Review+1，除非这些更改是次要的且没有争议（例如，文档更改）。即便如此，我们仍鼓励由第二位委员会成员进行独立审核。
对于较小的 API 更改，尤其是对现有 API 的增量改进，代码审核通常足以让 API 审核者为更改提供 API-Review+1。但是，对于较大的更改，尤其是那些显著扩展 API Surface 的更改，API 设计者应编写 RFC（请参阅 Fuchsia RFC 模板），其中说明了 API 的设计，包括用 例和示例，以及安全和隐私注意事项。API 审核者始终可以要求 API 设计者编写 RFC，即使对于较小的更改也是如此，如果 API 审核者认为仅通过代码审核无法放心地批准更改。
如需纳入 Fuchsia SDK，API 必须克服两个障碍：必须有 现成的客户愿意使用该 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 校准会话（请参阅下一部分）的议程中安排一个时间段，以便将 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 治理方面的经验，并对本文档的早期草稿提供了周到的反馈。