1. 网络子系统 (netdev)

1.1. tl;dr

  • 将您的补丁指定到一棵树 - [PATCH net] 或 [PATCH net-next]

  • 对于修复，无论在哪棵树上，都需要 Fixes: 标签

  • 不要发布大型系列（> 15 个补丁），将它们分解

  • 不要在 24 小时内重新发布您的补丁

  • 反向圣诞树

1.2. netdev

netdev 是一个邮件列表，用于讨论所有与网络相关的 Linux 内容。这包括 Linux 源代码树中 net/ 下的所有内容（例如 IPv6 等核心代码）和 drivers/net 下的所有内容（例如特定硬件驱动程序）。

请注意，某些子系统（例如无线驱动程序）的流量很大，它们有自己的特定邮件列表和树。

与许多其他 Linux 邮件列表一样，netdev 列表托管在 kernel.org 上，其存档可在 https://lore.kernel.org/netdev/ 上找到。

除了上面提到的那些子系统之外，所有与网络相关的 Linux 开发（即 RFC、评审、评论等）都在 netdev 上进行。

1.3. 开发周期

以下是关于 Linux 开发节奏的一些背景信息。每个新版本都以两周的“合并窗口”开始，在此期间，主要维护人员将他们的新内容提供给 Linus 进行合并到主线树中。两周后，合并窗口关闭，它被调用/标记为 -rc1。此后不会有新功能加入主线，只允许对 rc1 内容进行修复。在收集了大约一周的 rc1 内容的修复后，会发布 rc2。这会大致每周重复一次，直到 rc7（通常情况下；如果情况平静，有时是 rc6，如果情况动荡，则为 rc8），在完成最后一个 vX.Y-rcN 一周后，会发布正式的 vX.Y。

要了解我们现在处于周期的哪个位置 - 在此处加载主线 (Linus) 页面

并注意“tags”部分的顶部。如果是 rc1，则表示处于开发周期的早期阶段。如果一周前标记为 rc7，则可能即将发布。如果最近的标签是最终发布标签（没有 -rcN 后缀）- 我们很可能处于合并窗口中，并且 net-next 已关闭。

1.4. git 树和补丁流

有两个正在使用的网络树（git 存储库）。它们都由主要网络维护人员 David Miller 驱动。有一个 net 树，以及 net-next 树。正如您可能从名称中猜到的那样，net 树用于修复来自 Linus 的主线树中已有的现有代码，而 net-next 是新代码进入未来版本的地方。您可以在此处找到这些树

将其与内核开发联系起来：在为期 2 周的合并窗口开始时，net-next 树将关闭 - 没有新的更改/功能。过去大约 10 周积累的新内容将通过拉取请求传递给主线/Linus，以用于 vX.Y -- 同时，net 树将开始积累与 vX.Y 相关的此拉取内容的修复。

通常会向 netdev 发送一条公告，说明 net-next 何时关闭，但了解以上内容，您可以提前预测到这一点。

警告

请勿在 net-next 树关闭期间向 netdev 发送新的 net-next 内容。

仅用于评审的 RFC 补丁显然在任何时候都受欢迎（使用 --subject-prefix='RFC net-next' 与 git format-patch）。

在两周过去后不久（并且 vX.Y-rc1 发布），net-next 的树重新打开，以收集下一个 (vX.Y+1) 版本的内容。

如果您没有订阅 netdev 和/或只是不确定 net-next 是否已重新打开，只需检查上面的 net-next git 存储库链接是否有任何新的与网络相关的提交即可。您还可以查看以下网站以了解当前状态

net 树继续收集 vX.Y 内容的修复，并定期（大约每周）反馈给 Linus。这意味着 net 的重点是稳定性和错误修复。

最后，vX.Y 发布，整个周期重新开始。

1.5. netdev 补丁评审

1.5.1. 补丁状态

可以通过查看 netdev 的主 patchwork 队列来检查补丁的状态

“状态”字段将准确告诉您补丁的当前状态

补丁状态

描述

新建，正在审查

待评审，补丁在维护者的评审队列中；这两种状态可互换使用（取决于当时处理 patchwork 的确切共同维护人员）

已接受

补丁已应用于相应的网络树，这通常由 pw-bot 自动设置

需要 ACK

正在等待来自区域专家或测试的 ack

请求更改

补丁未通过评审，预计会有包含适当代码和提交消息更改的新版本

已拒绝

补丁已被拒绝，不希望有新版本

不适用

补丁预计将在网络子系统之外应用

等待上游

补丁应由相应的子维护人员进行评审和处理，他们会将其发送到网络树；在 netdev 的 patchwork 中设置为 等待上游 的补丁通常会保持此状态，无论子维护人员是否请求更改、接受或拒绝了补丁

已推迟

补丁需要稍后重新发布，通常是因为依赖关系或因为它是为关闭的树发布的

已取代

已发布新版本的补丁，通常由 pw-bot 设置

RFC

不应用，通常不在维护人员的评审队列中，pw-bot 可以根据主题标签自动将补丁设置为此状态

补丁由携带它们的电子邮件的 Message-ID 标头索引，因此如果您在查找补丁时遇到问题，请将 Message-ID 的值附加到上面的 URL。

1.5.2. 更新补丁状态

贡献者和评审者没有权限直接在 patchwork 中更新补丁状态。Patchwork 没有公开太多关于补丁状态历史的信息，因此让多人更新状态会导致混乱。

netdev 没有委托 patchwork 权限，而是使用一个简单的邮件机器人，该机器人会在发送到邮件列表的电子邮件中查找特殊的命令/行。例如，要将一个系列标记为“请求更改”，需要在电子邮件线程中的任何位置发送以下行

pw-bot: changes-requested

因此，机器人会将整个系列设置为“请求更改”。当作者发现自己系列中的错误并希望防止其被应用时，这可能会很有用。

机器人的使用是完全可选的，如果有疑问，请完全忽略它的存在。维护人员将自行分类并更新补丁的状态。永远不应出于与机器人通信的主要目的向列表发送电子邮件，机器人命令应被视为元数据。

机器人的使用仅限于补丁的作者（补丁提交和命令上的 From: 标头必须匹配！），根据 MAINTAINERS 文件修改的代码的维护者（同样，From: 必须与 MAINTAINERS 条目匹配）和少数高级评审者。

机器人在此处记录其活动

1.5.3. 评审时间表

一般来说，补丁会很快（在 48 小时内）进行分类。但请耐心等待，如果您的补丁在 patchwork 中处于活动状态（即，它列在项目的补丁列表中），则被遗漏的可能性接近于零。

netdev 上的高开发量使评审人员相对较快地结束讨论。在沉默一周后，不太可能收到新的评论和回复。如果补丁在 patchwork 中不再处于活动状态，并且该线程闲置超过一周 - 请明确下一步骤和/或发布下一个版本。

对于 RFC 帖子，如果一周内没有人回复 - 评审人员要么错过了该帖子，要么没有强烈的意见。如果代码已准备就绪，请重新发布为 PATCH。

仅说“ping”或“bump”的电子邮件被认为是不礼貌的。如果您无法从 patchwork 中找出补丁的状态或讨论的落脚点 - 请描述您的最佳猜测并询问是否正确。例如

I don't understand what the next steps are. Person X seems to be unhappy
with A, should I do B and repost the patches?

1.5.4. 请求更改

标记为 请求更改 的补丁需要修改。新版本应附带更改日志，最好包括指向以前帖子的链接，例如

[PATCH net-next v3] net: make cows go moo

Even users who don't drink milk appreciate hearing the cows go "moo".

The amount of mooing will depend on packet rate so should match
the diurnal cycle quite well.

Signed-off-by: Joe Defarmer <[email protected]>
---
v3:
  - add a note about time-of-day mooing fluctuation to the commit message
v2: https://lore.kernel.org/netdev/[email protected]/
  - fix missing argument in kernel doc for netif_is_bovine()
  - fix memory leak in netdev_register_cow()
v1: https://lore.kernel.org/netdev/[email protected]/

提交信息应进行修订，以解答审阅者在之前的讨论中提出的任何问题。有时，提交信息的更新将是新版本中唯一的更改。

1.5.5. 部分重发

请始终重新发送整个补丁系列，并确保为补丁编号，以便清楚地表明这是可以应用的最新最好的补丁集。不要尝试仅重新发送已更改的补丁。

1.5.6. 处理应用错误的补丁

有时，补丁系列会在收到关键反馈之前被应用，或者应用了错误的系列版本。

一旦推送出去，就不可能让补丁消失，netdev树中的提交历史是不可变的。请在已合并的内容之上发送增量版本，以便修复补丁，使其看起来像最新的补丁系列将被合并时的样子。

在需要完全还原的情况下，必须将还原作为补丁提交到列表中，并在提交信息中说明还原提交的技术问题。还原应作为最后的手段，当原始更改完全错误时使用；首选增量修复。

1.5.7. 稳定树

虽然过去 netdev 提交不应该带有明确的 CC: [email protected] 标签，但现在情况已不再如此。请遵循Documentation/process/stable-kernel-rules.rst中的标准稳定规则，并确保包含适当的 Fixes 标签！

1.5.8. 安全修复

如果您认为自己发现了一个可能具有安全隐患的错误，请勿直接通过电子邮件联系 netdev 维护人员。当前的 netdev 维护人员一直要求人们使用邮件列表，而不是直接联系。如果您对此不满意，则可以考虑发送邮件至 security@kernel.org 或阅读有关 http://oss-security.openwall.org/wiki/mailing-lists/distros 的内容，以作为可能的替代机制。

1.5.9. 协同发布对用户空间组件的更改

应将使用内核功能的用户空间代码与内核补丁一起发布。这使审阅者有机会了解任何新接口的使用方式以及它的工作效果。

当用户空间工具驻留在内核存储库本身中时，所有更改通常应作为一个系列发布。如果系列过大，或者用户空间项目未在 netdev 上进行审阅，请包含一个指向公共存储库的链接，以便查看用户空间补丁。

如果用户空间工具位于单独的存储库中，但在 netdev 上进行审阅（例如，对 iproute2 工具的补丁），则在发布到邮件列表时，内核和用户空间补丁应形成单独的系列（线程），例如：

[PATCH net-next 0/3] net: some feature cover letter
 └─ [PATCH net-next 1/3] net: some feature prep
 └─ [PATCH net-next 2/3] net: some feature do it
 └─ [PATCH net-next 3/3] selftest: net: some feature

[PATCH iproute2-next] ip: add support for some feature

不建议将它们发布为一个线程，因为它会混淆 patchwork（截至 patchwork 2.2.2）。

1.6. 准备更改

注重细节很重要。像审阅者一样重新阅读自己的工作。您可以首先使用 checkpatch.pl，甚至可以使用 --strict 标志。但不要盲目地机械地这样做。如果您的更改是错误修复，请确保您的提交日志指示最终用户可见的症状，发生的原因，然后在必要时解释为什么提出的修复是完成此事的最佳方法。不要破坏空白，并且像通常一样，不要错误地缩进跨多行的函数参数。如果这是您的第一个补丁，请将其发送给自己，以便您可以在未打补丁的树上测试应用它，以确认基础设施没有损坏它。

最后，请返回并阅读Documentation/process/submitting-patches.rst，以确保您没有重复其中记录的某些常见错误。

1.6.1. 指示目标树

为了帮助维护人员和 CI 机器人，您应该明确标记您的补丁的目标树。假设您使用 git，请使用前缀标志

git format-patch --subject-prefix='PATCH net-next' start..finish

对于错误修复 net 内容，请在上面的示例中使用 net 而不是 net-next（始终使用小写）。

1.6.2. 将工作划分为补丁

设身处地为审阅者着想。每个补丁都是单独阅读的，因此应构成朝着您既定目标迈出的可理解的一步。

避免发送长度超过 15 个补丁的系列。较大的系列需要更长的时间来审阅，因为审阅者会推迟查看它，直到他们找到一大块时间。可以在短时间内审阅一个小型系列，因此维护人员会直接执行。结果，较小系列的序列可以更快地合并，并具有更好的审阅覆盖率。重新发布大型系列也会增加邮件列表的流量。

1.6.3. 局部变量排序（“反向圣诞树”、“RCS”）

Netdev 有一个约定，用于对函数中的局部变量进行排序。将变量声明行按从最长到最短的顺序排列，例如：

struct scatterlist *sg;
struct sk_buff *skb;
int err, i;

如果变量之间存在阻止排序的依赖关系，请将初始化移出内联。

1.6.4. 格式优先级

在现有代码中使用非标准格式时，请使您的代码遵循最新的指南，以便最终 netdev 域中的所有代码都采用首选格式。

1.6.5. 使用设备管理和 cleanup.h 构造

Netdev 对所有“自动清理” API（包括甚至 devm_ 助手）的承诺仍然持怀疑态度。它们不是首选的实现样式，仅是可接受的样式。

在任何长度超过 20 行的函数中，都不建议使用 guard()，而 scoped_guard() 被认为更具可读性。仍然（弱）首选使用正常的锁定/解锁。

在构建 API 和助手（尤其是范围迭代器）时，可以使用低级清理构造（例如 __free()）。但是，不建议在网络核心和驱动程序中直接使用 __free()。类似的指导也适用于在函数中间声明变量。

1.6.6. 清理补丁

Netdev 不鼓励执行简单清理的补丁，这些清理不是在其他工作的上下文中进行的。例如

  • 解决 checkpatch.pl 警告

  • 解决 局部变量排序 问题

  • 转换为设备管理的 API（devm_ 助手）

这是因为人们认为此类更改产生的混乱成本高于此类清理的价值。

相反，不阻止拼写和语法修复。

1.6.7. 审阅后重新发送

在两次发布之间至少间隔 24 小时。这将确保所有地理位置的审阅者都有机会发表意见。也不要在两次发布之间等待太久（数周），因为它会使审阅者难以回忆起所有上下文。

确保您在新的发布中解决了所有反馈。如果关于先前版本的讨论仍在进行中，请勿发布新版本的代码，除非审阅者直接指示。

新版本的补丁应作为单独的线程发布，而不是作为对先前发布的回复。更改日志应包含指向先前发布的链接（请参阅请求的更改）。

1.7. 测试

1.7.1. 预期的测试级别

至少，您的更改必须在设置 W=1 的情况下通过 allyesconfig 和 allmodconfig 构建，而不会出现新的警告或失败。

理想情况下，您将已完成特定于您的更改的运行时测试，并且补丁系列包含一组 tools/testing/selftests/net 的内核自测或使用 KUnit 框架的自测。

您应该在相关的网络树（net 或 net-next）之上测试您的更改，而不是例如稳定树或 linux-next。

1.7.2. patchwork 检查

patchwork 中的检查主要是围绕现有内核脚本的简单包装器，源代码位于

https://github.com/linux-netdev/nipa/tree/master/tests

不要仅为了通过检查而发布补丁。您必须通过在发布到邮件列表之前在本地测试它们来确保您的补丁已准备就绪。patchwork 构建机器人实例很容易超载，如果我们能提供帮助，netdev@vger 真的不需要更多的流量。

1.7.3. netdevsim

netdevsim 是一个测试驱动程序，可用于在不需要功能强大的硬件的情况下练习驱动程序配置 API。强烈建议在添加新的 API 时使用基于 netdevsim 的模拟和测试，但是 netdevsim 本身不被视为用例/用户。您还必须在实际驱动程序中实现新的 API。

我们不保证 netdevsim 将来不会以会破坏通常被认为是 uAPI 的方式发生变化。

netdevsim 仅保留用于上游测试，因此任何新的 netdevsim 功能都必须附带 tools/testing/selftests/ 下的自测。

1.8. 审阅者指南

强烈建议大家在邮件列表中审查他人的补丁，无论专业水平如何。有关一般指导和有用的提示，请参阅审查补丁。

可以安全地假设 netdev 维护者了解社区和审查者的专业水平。审查者不应担心他们的评论会阻碍或破坏补丁流程。

强烈鼓励经验较少的审查者对提交的内容进行更深入的审查，而不是仅仅关注代码格式、标签等琐碎或主观的问题。

1.9. 推荐/反馈

一些公司在员工绩效评估中使用同行反馈。如果您花费大量时间审查代码并竭尽全力改进共享基础设施，请随时向 netdev 维护者请求反馈。

反馈必须由您（贡献者）请求，并且始终会与您分享（即使您请求将其提交给您的经理）。