概览
本文档介绍了 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 工程理事会的运作。主席的职责如下：
- 安排会议。
- 为每次会议设置议程。
- 评估理事会是否已达成粗略共识。
功能区
| 领域 | 主要 | 次要 |
|---|---|---|
| 蓝牙 | jamuraa@google.com | silberst@google.com |
| 组件框架 | cgonyeo@google.com | quiche@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 |
| 身份 | 无 | 无 |
| 内核 | mcgrathr@google.com | rashaeqbal@google.com |
| 媒体 | dalesat@google.com | ypomortsev@google.com |
| 指标 | frousseau@google.com | 无 |
| Netstack | brunodalbo@google.com | 无 |
| Power | mbrunson@google.com | prashanthsw@google.com |
| 产品组装 | aaronwood@google.com | awolter@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 | carolineliu@google.com |
| 虚拟化 | 无 | 无 |
| Web | wez@google.com | ianloic@google.com |
| WLAN | silberst@google.com | jamuraa@google.com |
随着项目的发展，功能领域列表（以及理事会的组成）也会随之发展。功能区列表由 Fuchsia 领导层维护。
在考虑添加区域时，议会会考虑以下因素：
- 覆盖率。此区域是否已包含在其他某个区域中，还是存在缺口？
- 范围。该区域是否足够大，需要专门任命一名代表？
- 持续需求。之前是否需要将此作为区域？
决策流程
如果理事会被要求做出决定，则决策流程如下。相关区域的议员是主要决策者，但整个议会是最终决策者。理事会作为一个整体，通过主席评估的大致共识做出决策。
主要决策者可以推迟做出决定，在这种情况下，理事会会做出决定。如果理事会未能达成大致共识，主席将做出最终决定。
理事会成员可以要求理事会推翻主要决策者的决定。如果理事会未能达成大致共识，则主要决策者做出的决定有效。
Operations
该委员会具有两项主要职能：API 审核和 API 校准。
API 审核
对 Fuchsia API Surface 的每次更改都需要获得理事会成员的批准。特定功能领域的变更通常应由负责该领域的理事会成员批准，但如果负责的理事会成员无法批准，则任何理事会成员都可以批准该变更。
在合并之前，每项修改 Fuchsia API Surface 的更改都必须获得 api-council@fuchsia.dev 成员的 API-Review+1，以及通常的 Code-Review+2。同一个人可以针对给定的更改提供 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-Review+1。
API 设计者或审核者可以向整个委员会提交 API RFC，方法是向主席申请在即将举行的 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 Council、Web API OWNERS、W3C 和 IETF 使用的管理结构。特别感谢 Jeff Brown、Dimitri Glazkov、Jeremy Manson、Rebecca Silberstein 和 Greg Simon 分享他们在 API 管理方面的经验，并针对本文档的早期草稿提供了周到的反馈。