本頁面由 Cloud Translation API 翻譯而成。

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(https://fxbug.dev/42075402):
將文字詞組當做要採取的行動。應該能其他貢獻者領取 TODO 而未諮詢外部相關人士內容，包括提及的問題

提供引文

當實作遵循某些規格/文件 (例如 RFC) 時附上註解，並引述相關部分文件。引述文字可讓讀者瞭解原因並且在引文中協助讀者取得更多背景資訊。

錯誤訊息

與程式碼註解一樣，請考量未來讀取錯誤訊息的讀取者。請確保錯誤訊息可供採取行動。舉例來說測試失敗訊息，例如「Unexpected value」- 一律納入；另一個範例「預期 <variable> 為空白，非空白」- 如果這則訊息含有未預期的元素，會更加實用。

請務必考量：讀者會如何處理這則訊息？

測試

如要瞭解一般性準則，請參閱可測試性評分量表。以及 Fuchsia 的測試撰寫和可測試性評論。在 Fuchsia 網路中請定義下列測試類別：

單元測試是一段完整本地的程式碼，依附元件為假或模擬
整合測試可驗證兩種以上不同行為之間的行為元件。
端對端測試是由外部主體機器驅動，並使用公開測試器的寫入網路的 API 和位元組來執行行為驗證。可以是透過實體網路執行，或藉由 DUT 的虛擬化執行 (qemu)。

編寫測試時，請考量下列準則：

請一律新增測試來測試新功能或錯誤修正。
寫入時，請參考錯誤訊息中的規範測試斷言
測試必須具有確定性。執行緒或時間相依程式碼，隨機數字產生器 (RNG) 和跨元件通訊非確定性的來源請參閱「編寫可重現的確定性測試」取得提示。
避免使用硬式編碼逾時進行測試。最好依賴。
偏好密封測試；測試設定處理常式應以明確的方式呈現確定性留意會同時執行案例的測試固件 (例如就像 Rust 這樣使用「ambient」時免費 Google Cloud 服務偏好明確插入是測試重要的元件依附元件。
測試應一律是元件。
適用於非端對端測試：虛擬裝置和網路。詳情請見 netemul 以取得虛擬網路環境的指南。
避免變更偵測工具測試。對變更執行不必要的敏感，尤其是程式碼以外的變更在測試中，可能會妨礙功能開發和重構。
不要將實作詳細資料編碼在測試中，而偏好透過公開模組的公用 API

解除包裝 FIDL 方法呼叫傳回的 Result<_, fidl::Error> 時，在恐慌訊息中重述呼叫的函式，使其更容易追蹤來電網站請勿重複出現該錯誤類型，因為已然會包含在恐慌輸出中例如：

// 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.

原始碼控管最佳做法

修訂條款應便於閱讀；也就是附隨性的變更例如程式碼移動或格式設定變更實際的程式碼變更

承諾應一律聚焦。例如，修訂版本可新增特徵請修正錯誤或重構程式碼，但請勿混合使用。

承諾使用合約規模應謹慎挑選；避免過度大型或複雜的修訂版本能以邏輯方式分隔，但也請避免使用過度分隔的修訂版本需要審查程式碼，才能將多個修訂版本載入其心理工作記憶體才能正確地瞭解各部分如何相輔相成。如果您的需要多個修訂版本文件或 RFC 文件

修訂訊息

修訂訊息應簡明扼要，但也要獨立完整 (避免依賴問題) 以書面表示對變更有用 (包括理由和任何必要背景資訊)。

避免過多的細節或敘述。

修訂訊息應包含簡短主旨行和個別說明段落，如下所示：

如果主題容易理解，可省略本主體；例如：修正了錯字。Git 書籍包含修訂版本指南部分大部分相同建議，而且此清單是某個網誌的一部分張貼者：Chris Beams。

修訂訊息應使用 Issue Tracker 整合功能。請參閱修訂訊息樣式指南。

使用 Issue Tracker 整合功能時，請不要省略可能會缺少必要內容描述也包含相關問題 (提交訊息應該精簡，但獨立)。許多問題是 Google 內部造成，提供的 Issue Tracker 在提交修訂版本時無法保證能夠使用已讀取紀錄

修訂訊息不得含有下列任一項目的參照：

歷年來段的相對片段
非公開網址
個人
代管程式碼審查 (例如 fuchsia-review.googlesource.com)
- 以 SHA-1 雜湊參照這個存放區中的修訂版本
- 參照其他存放區中的修訂版本，其中透過公開網址 (例如 https://fuchsia.googlesource.com/fuchsia/+/67fec6d)
其他實體可能不適合未來讀者使用

建議您在修訂訊息中加入 Test: 行。Test: 行應：

凡是行為改變或添加內容，均已全面測試。
說明如何執行新的/受影響的測試案例。

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

程式碼審查規範

程式碼審查流程

網路堆疊團隊會採用下列程式碼審查規範：

作者：

CL 可送審時，請向列出的團隊成員提出審查要求位於最接近的 OWNERS 檔案中
如果您的 CL 進行了重大變更，請同時新增次要審查人員從 src/connectivity/network/OWNERS 中選出。這項動作應該同時要求擁有者審查您可以選擇任何團隊您想要的會員；請考慮以下條件：
- 列在以下位置的可讀性審查人員： src/connectivity/network/tests/integration/common/OWNERS敬上。
- 增加目標區域內。
- 在約略相關區域工作。
- 提供語言/模式的相關經驗。
從最接近的 OWNERS 檔案新增評論者之前，您可以新增將 fuchsia-netstack-reviews@google.com 設為評論者。gwsq 機器人會從群組中隨機挑選審查員
強烈建議同時從這兩個評論人員 +2，但不嚴格無從得知

審查者：

如果無法充分掌握 +2 的當地知識，這是正確做法我們會盡力審查雙方語言、風格、模式或通則及 +1
請務必以您是唯一審查者的方式審查程式碼。
盡量避免將審查的部分內容委派給他人 - 「比較熟悉這個部分」。
無論當地擁有者為何，您都能有效地進行程式碼審查。
建議擁有者審查人員先讓次要審查者略過擁有者 +2 之後，就會有強烈的錨定效應降低挑戰和學習機會次要審查人員可能會要求接受第一筆通行證或業主審查人員，可能會讓第二名通過並在 CL 上留言，說明該意圖相反情況，即並不建議要求擁有者先行通過第二名審查。

請注意，這種配置可能會增加審查作業的延遲時間，我們希望盡量減少遇到以下情況時，請試著縮短延遲時間他們會要求審查或處理留言我們致力於將延遲時間維持在 24 小時內。供作者和審查人員參考如果超過 24 小時，不要害怕發出連線偵測 (ping)。 Gerrit 通知設定和智慧型電子郵件篩選器，對提升成效的助益。不受干擾此外，請勇於回應評論，

我們建議區域擁有者為所在地區建立 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