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 維護者請求反饋，特別是如果您花費大量時間審閱程式碼並盡力改進共享基礎設施。

反饋必須由您，即貢獻者請求，並且始終會與您分享（即使您請求將其提交給您的經理）。