概览
本文档介绍了 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 能够有效保护用户隐私、帮助最终开发者完成特定任务，并让 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 Eng 委员会的运作。主席承担以下责任：
- 安排会议。
- 设置每次会议的议程。
- 评估委员会是否已达成大致共识。
职能领域
| 领域 | 主要 | 次要 |
|---|---|---|
| 蓝牙 | 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 | hjfreyer@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 | diserovich@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 领导层维护。
在考虑添加区域时，委员会会考虑以下因素：
- 覆盖率。此区域是否已被其他区域覆盖，或者是否存在间隙？
- 范围。该区域是否足够大，需要专门的指定人员？
- 持续的需求。之前是否需要将此区域作为区域？
决策流程
如果需要委员会做出决策，决策流程如下。相关区域的议会成员是主要决策者，但议会整体是最终决策者。理事会作为一个整体，通过大致共识做出决策，并由主席进行评估。
主要决策者可以推迟决策，在这种情况下，委员会将做出决策。如果委员会未能达成大致共识，主席将做出最终决定。
委员会成员可以要求委员会推翻主要决策者的决定。如果委员会未能达成大致共识，则以主要决策者做出的决定为准。
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 审核者不希望仅通过代码审核来批准更改，也可以要求撰写 RFC。
如需纳入 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 校准会议（请参阅下一部分）的议程中安排一个时段，从而将 API RFC 提交给整个委员会。例如，如果 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 OWNERS、W3C 和 IETF 所使用的治理结构。特别感谢 Jeff Brown、Dimitri Glazkov、Jeremy Manson、Rebecca Silberstein 和 Greg Simon 分享他们在 API 治理方面的经验，并对本文档的早期草稿提供宝贵反馈。