Fuchsia 网络贡献者指南

Fuchsia Networking 欢迎各方的贡献。本文档定义了贡献准则，这些准则与适用于整个 Fuchsia 的准则有何不同，或者对适用于整个 Fuchsia 的准则进行了改进。

使用入门

请参阅使用入门文档，设置您的开发环境。

捐助者计划工作流程

如需一般性的贡献指南和整个项目的最佳做法，请参阅贡献更改文档。本文档的其余部分介绍了特定于 Fuchsia 网络的最佳做法。

编码指南

哲学

本部分的灵感来自 Flutter 的样式指南，该指南包含您应应用于所有编程工作的许多一般原则。阅读。下面列出了我们认为特别重要的具体方面。

偷懒

请勿实现您不需要的功能。很难正确设计未使用的代码。这与上文给出的提交内容大小调整建议密切相关；添加要在将来的某些提交中使用的新数据结构就像添加您不需要的功能一样 - 代码审核人员很难确定您是否设计了正确的结构，因为他们（和您！）无法了解该结构的使用方式。

深入兔洞

您偶尔会遇到让您感到惊讶或错误的行为。很有可能！请花时间找出根本原因：您要么从中学到东西，要么解决某个问题，这两种方法都值得您花时间。不要解决您不理解的行为。

避免重复

尽可能避免重复代码。如果现有代码未以适合您需求的方式公开，最好将必要的部分提取到通用依赖项中。

错误处理

避免使用未处理的错误和本身不允许进行适当错误处理的 API；有关常见示例，请考虑使用 fuchsia_async::executor::spawn。spawn 本身不会传递错误（因为执行流程已被中断）。在大多数情况下，spawn 可以替换为后续包含在 select 表达式中的 Future（示例提交），或者直接对 await 执行await操作（示例提交）。

运行时编译时

相较于运行时不变的检查，更倾向于类型安全。换言之，您应该安排抽象化，使其不能表达无效条件，而不是在运行时依赖于断言。

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

避免使用魔数。

注释

撰写评论时，请花点时间考虑一下您评论的潜在读者。确保注释是完整的句子，并且语法和标点符号都正确无误。请注意，添加更多注释或更详细的注释并不总是更好；例如，请避免重复对其所锚定代码的评论。

文档注释应保持独立；换句话说，不要假设读者知道相邻文件或相邻结构中的文档。避免在文档注释中说明该类型的实例；例如，AddressSet is a set of client addresses. 是描述 AddressSet 类型的字段的注释，但该类型可用于保存任何类型的 Address，而不仅仅是客户端的。

对注释使用短语，以避免可能变得过时的引用；例如：尽可能不要按名称提及变量或类型（某些文档注释是必要的例外情况）。此外，还应避免提及过去或未来版本或者过去或未来的作品，也应避免提及相关内容的记录；根据基本原则进行说明，而不是引用外部内容（包括过去的修订版本）。

编写 TODO 时：

1. 使用 TODO(https://fxbug.dev/42075402): 格式添加问题参考编号
2. 将文本表述为要采取的操作；其他贡献者应该可以在不咨询任何外部来源（包括引用的问题）的情况下直接拿到 TODO。

提供引用

如果实现遵循某些规范/文档（例如 RFC），请在实现代码附近添加一条注释，并附上对文档相关部分的引用和引用。引文可让读者了解您做某件事的原因，而引用则可以让读者了解更多背景信息。

错误消息

与代码注释一样，请考虑代码发出的错误消息的未来查看者。确保错误消息具有可操作性。例如，应避免显示“意外值”等测试失败消息，其中应始终包含意外值；另一个示例是“预期 <variable> 为空，是非空”- 如果此消息包含意外元素，会非常有用。

请务必考虑：读者会如何处理此邮件？

测试

请查阅可测试性评分准则，了解有关 Fuchsia 上测试编写和可测试性审核的一般准则。在 Fuchsia Networking 中，我们定义了以下测试类：

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

编写测试时，请遵循以下准则：

1. 请务必添加测试，以便开发新功能或修复 bug。
2. 编写测试断言时，请参考错误消息中的准则。
3. 测试必须具有确定性。线程或具有时效性的代码、随机数生成器 (RNG) 以及跨组件通信都是常见的不确定性来源。如需了解相关提示，请参阅编写可重现的确定性测试。
4. 避免使用硬编码超时进行测试。更倾向于依赖框架/夹具来使测试超时。
5. 首选封闭测试；测试设置例程应具有明确的确定性。使用“环境”服务时，请注意并行运行各种用例的测试夹具（例如 Rust）。最好明确注入对测试至关重要的组件依赖项。
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 Beams 的博文的一部分。

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

使用问题跟踪器集成时，请勿省略可能也包含在相关问题中的必要上下文（提交消息应简洁但自成一体。许多问题都是 Google 内部发现的，无法保证在读取提交历史记录时任何给定的问题跟踪器都可用。

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

1. 相对时刻
2. 非公开网址
3. 个人
4. 托管的代码审核（例如 fuchsia-review.googlesource.com 上）
   • 按 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 中选择的辅助审核者。应该在向所有者申请审核的同时，发生这种情况。您可以选择任何团队成员；请考虑以下条件：
  • 如果 CL 主要包含对 netemul 集成测试的更改，则在 src/connectivity/network/tests/integration/common/OWNERS 中被列为可读性审核程序。
  • 目标区域渐入佳境。
  • 从事相关领域的工作。
  • 具备语言/模式方面的经验。
• 在从最近的 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