Fuchsia 网络贡献者指南

Fuchsia Networking 欢迎所有人的大力贡献。本文档定义了 与投稿指南有何不同之处，或者对这些准则进行完善 适用于整个 Fuchsia。

使用入门

请参阅入门文档，了解如何设置您的 开发环境。

捐助者计划工作流程

如需了解常规问题，请参阅贡献更改文档 贡献指导和项目级最佳实践。这一过程 文档介绍了特定于 Fuchsia 网络的最佳做法。

编码指南

哲学

本部分的灵感来自 Flutter 的风格指南，该指南 包含许多一般原则，您应当在您的所有编程工作中 工作。读一读。下面列出了我们认为 尤其重要。

偷懒

请勿实现不需要的功能。很难正确设计未使用的 代码。这与上述承诺容量建议密切相关；添加 在未来的提交中使用新的数据结构，类似于添加特征 因为代码审核者很难确定 您的结构是正确的，因为他们（和您！）无法了解 。

深入兔子洞

您偶尔会遇到出乎您意料或看起来不正确的行为。它 很可能是！花时间找出根本原因 - 您有两种选择： 无论是做某件事，还是修理一件事，都值得花时间学习。不解决 行为

避免重复

请尽可能避免重复代码。如果没有现有代码 以符合您需求的方式公开，则最好提取 分为一个共同的依赖项。

错误处理

避免出现未处理的错误和本身会妨碍正确处理错误的 API； 以 fuchsia_async::executor::spawn 为例。 spawn 本身会排除错误传递（因为执行流程是 已终止）。在大多数情况下，spawn 可以替换为将来的 Future 包含在 select 表达式中（提交示例）或 await直接提交示例)。

运行时的编译时

更注重类型安全，而不是运行时不变性检查。也就是说， 使它们无法表达无效条件 依赖项。

编写可测试的代码；可测试的代码是模块化的，其依赖项可以轻松 注入。

避免使用魔数。

评论

在撰写评论时，请花点时间考虑您的 评论。请确保您的注释是语法正确的完整句子 和标点符号。请注意，添加评论或详细评论 总会更好；例如，避免在注释中重复锚定它们的代码 。

文档注释应保持独立；换句话说，不要假设 让读者知道相邻文件或相邻文件中的文档 结构。避免为描述以下对象的实例的类型添加文档注释 类型；例如，AddressSet is a set of client addresses. 是一条评论 它描述了AddressSet类型的字段，但该类型可用于 任何种类的Address，而不仅仅是客户的。

措辞会以避免提及可能会过时的内容；例如： 尽可能不要按名称提及变量或类型（某些文档注释 属于必要的例外情况）。另外，请避免引用 或过去或将来与被记录的项目相关的工作；解释一下 而不是通过外部引用（包括过去 修订）。

编写 TODO 时：

1. 请按以下格式添加问题参考编号：TODO(https://fxbug.dev/42075402):
2. 将文字表述为要采取的行动；应该能够 在未咨询任何外部人员的情况下，由另一个贡献者完成该待办事项 包括提到的问题。

提供引用

当实现遵循某些规范/文档（例如 RFC）时， 在评论中包含对以下内容的引用和引用 实现附近的文档。引语可让读者了解某些内容 引用的内容可帮助读者获得更多背景信息。

错误消息

与代码注释一样，请考虑发出的错误消息的未来读取者 由代码决定确保错误消息可操作。例如，避免 测试失败消息，例如“意外值”始终包含意外的 值；另一个示例是“<variable> 应该为空，之前是非空”- 如果其中包含意外元素，此消息会更有用。

请务必考虑：读者将对这条消息做些什么？

测试

如需关于以下方面的一般准则，请参阅可测试性评分准则 Fuchsia 上的测试编写和可测试性审核。在 Fuchsia Networking 中， 定义以下测试类：

• 单元测试完全位于一段代码及其所有外部 是虚构的或模拟的
• 集成测试用于验证两个或更多个不同 组件。
• 端到端测试由外部主机驱动，并使用公共 写入网络的 API 和字节，用于执行行为验证。可以是 通过物理网络或 DUT 的虚拟化 (qemu) 执行。

在编写测试时，请考虑以下准则：

1. 务必添加测试，以获取新功能或问题修复。
2. 在编写时，请参考错误消息中的准则 测试断言。
3. 测试必须具有确定性。线程代码或具有时效性的代码，随机 数字生成器 (RNG) 和跨组件通信很常见 是不确定性的基础。请参阅编写可重现的确定性测试 获取提示。
4. 避免使用硬编码超时测试。更倾向于依赖 使测试超时。
5. 首选封闭测试；测试设置例程应明确且 是确定性的。请注意并行运行多个用例的测试夹具（例如 使用“ambient”时服务。倾向于显式注入 组件依赖项。
6. 测试应始终是组件。
7. 首选使用虚拟设备和网络进行非端到端测试。请参阅 netemul，用于获取有关虚拟网络环境的指导。
8. 避免更改检测器测试； 对更改（尤其是代码外部的更改）过于敏感 可能会妨碍功能开发和重构。
9. 请勿在测试中编码实现细节，最好通过 模块的公共 API 中。

10. 解封从 FIDL 方法调用返回的 Result<_, fidl::Error> 时， 重报 panic 消息中正在调用的函数，以便更轻松地 跟踪调用点。不要重复错误类型， 。例如：

    // Bad:
    let foo_result = proxy
        .foo() // `foo` returns a `Result<_, fidl::Error>`.
        .await
        .expect("FIDL error"); // Doesn't provide any new information.
    
    // Good:
    let foo_result = proxy
        .foo() // `foo` returns a `Result<_, fidl::Error>`.
        .await
        .expect("calling foo"); // Restate the function being called.
    

源代码控制最佳实践

提交的内容应便于阅读；即附带更改 （例如代码移动或更改格式）都必须与 实际的代码更改。

提交应始终重点突出。例如，提交可以添加特征 修复 bug 或重构代码，但不能进行混合。

提交的内容大小应经过深思熟虑：避免过大或复杂的提交 这在逻辑上可以分开，但也要避免过于分离的提交 需要通过代码审核将多项提交内容加载到其心理工作记忆中 从而正确理解各部分是如何协同工作的。如果您的 更改需要多次提交，请考虑这些更改是否有必要 设计文档或 RFC。

提交消息

提交消息应简洁但保持独立（避免依赖问题 参考资料作为更改的解释说明），并且编写得非常有帮助 为将来阅读的用户提供（包括提供理由和任何必要的背景信息）。

避免不必要的细节或叙事。

提交消息应由简短的主题行和单独的 解释段落：

1. 使用空白行将主题与正文分开
2. 将主题行限制在 50 个字符以内
3. 主题行大写
4. 请勿在主题行末尾添加句点
5. 在主题行中使用祈使语气
6. 正文长度为 72 个字符
7. 在正文中说明内容是什么、原因和方式

如果主语不言自明，则正文可省略；例如修复 拼写错误。Git 手册包含提交指南部分 大部分都是类似的建议，而上述列表是 发布者：Chris Beam。

提交消息应使用问题跟踪器集成。请参阅提交消息样式指南。

使用问题跟踪器集成时，请勿遗漏必要的上下文， 也会包含在相关问题中（提交消息 简洁但独立）。许多问题都是 Google 内部问题， 不保证在提交时指定的问题跟踪器可用 历史记录。

提交消息不得包含对以下任一项的引用：

1. 相对时刻
2. 非公开网址
3. 个人
4. 托管的代码审核（例如在 fuchsia-review.googlesource.com 上） <ph type="x-smartling-placeholder">
   </ph>
   • 按 SHA-1 哈希引用此代码库中的提交内容
   • 通过公共网址（例如 https://fuchsia.googlesource.com/fuchsia/+/67fec6d)
5. 其他可能对任意未来读者没有意义的实体

建议在提交消息中添加 Test: 行。Test: 线 应该：

1. 证明任何行为变更或添加都经过全面测试。
2. 说明如何运行新测试用例/受影响的测试用例。

例如：Test: Added new unit tests. `fx test netstack-gotests`。

代码审核指南

代码审核流程

Netstack 团队采用了以下代码审核准则：

作者：

• 您的 CL 可供审核后，请向所列团队成员提出审核申请 在最近的 OWNERS 文件中。
• 如果您的 CL 引入了重要更改，还应添加辅助审核者 从“src/connectivity/network/OWNERS”中挑选。这种情况应该发生 以及向所有者提出审核请求。您可以选择任意团队 所需的成员请考虑以下条件： <ph type="x-smartling-placeholder">
  </ph>
  • 被列为可读性审核者 src/connectivity/network/tests/integration/common/OWNERS 如果 CL 主要包含对 netemul 集成测试的更改，则会发生此错误。
  • 在目标区域磨合。
  • 从事略微相关的领域工作。
  • 拥有语言/模式经验。
• 在从最近的 OWNERS 文件添加评价者之前，您可以先将 Google 将 fuchsia-netstack-reviews@google.com 添加为审核人。GWSQ 聊天机器人 从群组中随机选择一个评价者。
• 强烈建议同时在两位评价者那里获得 +2，但并非严格要求 。

审核者：

• 如果你觉得自己没有足够的本地知识来 +2，这是正确的做法 在语言使用、风格、模式或 通用性和 +1。
• 请务必以您唯一审核者的身份审核代码。
• 如果可能，避免将审核的部分委托给他人，“您更熟悉 这一部分”。
• 无论本地所有权如何，以有意义的方式参与代码审核。
• 建议所有者审核者允许二级审核者首先进行审核 。所有者对 CL 执行 +2 操作后，将产生一种很强的锚定效果， 减少挑战和学习机会。二级审核员 申请第一通过，或者所有者审核人员可以授予第二重通过 在 CL 中发表评论，说明这一意图。反函数，即 二级审核人员不建议申请所有者完成第一轮审核。

请注意，此机制可能会增加审核的延迟时间，但会带来负面影响 希望最小化的效果在出现以下任一情况时，请尽量缩短延迟时间 请求对评论进行审核或处理。我们致力于将延迟时间控制在 24 小时以内 作者和审校者。如果已经超过 24 小时，请不要害怕 Ping。 Gerrit 通知设置和智能电子邮件过滤器对于提高 这些干扰另外，不要害怕 ping 查看评价。

我们建议区域所有者为自己的区域创建 Gerrit 通知过滤器 来帮助落实这些准则和设计愿景。

提示与技巧

fx set

运行以下命令以构建所有测试及其依赖项：

fx set core.x64 --with //src/connectivity/network:tests

如果您正在执行会影响 fdio 和 third_party/go 的变更，请添加：

--with //sdk/lib/fdio:tests --with //third_party/go:tests