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 周积累的新内容将通过 vX.Y 的拉取请求传递到主线/Linus -- 同时，net 树将开始累积与 vX.Y 相关的此拉取内容的修复

通常会向 netdev 发送一个公告，指示 net-next 何时关闭，但了解以上内容，您可以提前预测。

警告

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

仅发送以供审查的 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 队列来检查补丁的状态

“State” 字段将准确告诉您补丁的进展情况

补丁状态

描述

New, Under review

待审查，补丁在维护者的队列中等待审查；这两种状态可以互换使用（具体取决于当时处理 patchwork 的共同维护者）

Accepted

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

Needs ACK

等待来自领域专家或测试的确认

Changes requested

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

Rejected

补丁已被拒绝，预计不会有新版本

Not applicable

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

Awaiting upstream

补丁应由相应的子维护者审查和处理，他们会将其发送到网络树；在 netdev 的 patchwork 中设置为 Awaiting upstream 的补丁通常会保持此状态，无论子维护者是否要求更改、接受或拒绝该补丁

Deferred

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

Superseded

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

RFC

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

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

1.5.2. 更新补丁状态

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

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

pw-bot: changes-requested

因此，机器人会将整个系列设置为 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. Changes requested

标记为 Changes Requested 的补丁需要修改。新版本应附带更改日志，最好包括指向先前发布的链接，例如

[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 <joe@barn.org>
---
v3:
  - add a note about time-of-day mooing fluctuation to the commit message
v2: https://lore.kernel.org/netdev/123themessageid@barn.org/
  - fix missing argument in kernel doc for netif_is_bovine()
  - fix memory leak in netdev_register_cow()
v1: https://lore.kernel.org/netdev/456getstheclicks@barn.org/

应该修改提交消息以回答审查者在先前讨论中提出的任何问题。有时，更新提交消息将是新版本中唯一的更改。

1.5.5. 部分重新发送

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

1.5.6. 处理错误应用的补丁

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

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

在需要完全回退的情况下，回退必须作为补丁提交到列表，并附带提交消息，解释已回退提交的技术问题。回退应作为最后的手段使用，当原始更改完全错误时；首选增量修复。

1.5.7. 稳定树

虽然过去 netdev 提交不应该携带显式的 CC: stable@vger.kernel.org 标签，但现在情况并非如此。请遵循 Documentation/process/stable-kernel-rules.rst 中的标准稳定规则，并确保包含适当的 Fixes 标签！

1.5.8. 安全修复

如果您认为自己发现了一个可能具有安全影响的 Bug，请勿直接通过电子邮件发送给 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. 共同发布自检

自检应与代码更改属于同一系列。具体来说，对于修复，代码更改和相关测试应进入同一棵树（测试可能缺少 Fixes 标签，这是预期的）。不鼓励在单个提交中混合代码更改和测试更改。

1.7. 准备更改

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

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

1.7.1. 指示目标树

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

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

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

1.7.2. 将工作划分为补丁

将自己置于审查者的位置。每个补丁都是单独阅读的，因此应该构成朝着您既定目标的易于理解的步骤。

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

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

Netdev 具有在函数中对局部变量进行排序的约定。按最长到最短的顺序排列变量声明行，例如

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

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

1.7.4. 格式优先级

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

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

Netdev 仍然对所有“自动清理”API 的承诺持怀疑态度，包括 devm_ 助手，从历史上看。它们不是首选的实现样式，而只是可接受的样式。

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

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

1.7.6. 清理补丁

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

  • 解决 checkpatch.pl 警告

  • 解决 局部变量排序 问题

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

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

相反，不鼓励拼写和语法修复。

1.7.7. 审查后重新发送

在两次发布之间至少留出 24 小时。这将确保来自所有地理位置的审查者都有机会参与。两次发布之间也不要等待太久（几周），因为这将使审查者更难回忆起所有上下文。

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

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

1.8. 测试

1.8.1. 预期的测试级别

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

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

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

1.8.2. patchwork 检查

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

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

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

1.8.3. netdevsim

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

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

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

1.9. 驱动程序的支持状态

Netdev 为想要在 MAINTAINERS 文件中获得 Supported 状态的驱动程序定义了其他要求。Supported 驱动程序必须运行所有上游驱动程序测试，并每天两次报告结果。不符合此要求的驱动程序应使用 Maintained 状态。目前，上游对 Supported 和 Maintained 驱动程序的处理方式没有区别。

驱动程序必须遵循的确切规则才能获得 Supported 状态

  1. 必须运行 Linux 自检的 drivers/net 和 drivers/net/hw 目标下的所有测试。运行和报告私有/内部测试也欢迎，但上游测试是必须的。

  2. 最低运行频率为每 12 小时一次。必须从选定的分支源测试指定的分支。请注意，分支是自动构建的，并且容易受到有意的恶意补丁发布的影响，因此测试系统必须隔离。

  3. 支持多代设备的驱动程序必须测试来自每一代的至少一个设备。测试平台清单（确切格式待定）应描述测试的设备型号。

  4. 测试必须可靠地运行，如果跳过多个分支或由于执行环境问题导致测试失败，则将撤销 Supported 状态。

  5. 由于驱动程序或测试本身的错误或缺乏对测试目标的特征的支持而导致的测试失败，不是失去 Supported 状态的基础。

netdev CI 将维护一个受支持设备的官方页面，列出其最近的测试结果。

驱动程序维护者可以安排其他人运行测试，不要求列为维护者的人员（或其雇主）负责运行测试。欢迎供应商、托管 GH CI、linux-netdev 下的其他仓库等之间的合作。

有关 netdev CI 的更多信息，请参阅 https://github.com/linux-netdev/nipa/wiki。如有任何问题，请随时联系维护者或列表。

1.10. 审查者指导

强烈鼓励在列表中审查其他人的补丁，无论专业知识水平如何。有关一般指导和有用提示，请参阅 审查补丁。

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

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

1.11. 推荐信/反馈

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

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