Fuchsia 網路貢獻者指南

Fuchsia Networking 歡迎大家捐款。本文件定義內容與 Fuchsia 適用指南相異或修正的貢獻規範。

踏出第一步

請參閱入門指南文件來設定您的開發環境。

貢獻者工作流程

如要瞭解一般貢獻指南和專案層級的最佳做法，請參閱貢獻變更文件。本文件的其餘部分將說明 Fuchsia 網路特有的最佳做法。

程式設計指南

哲學

本節以 Flutter 樣式指南為靈感，其中包含許多一般原則，應適用於所有程式設計工作。閱讀。以下將說明我們對於哪些方面特別重視。

懶骨頭

請勿導入您不需要的功能。難以正確設計未使用的程式碼。這與上述的修訂版本規模建議密切相關；新增要在日後修訂中使用的新資料結構，就像新增不需要的功能一樣。這比加入不需要的功能非常困難，因為它們 (和您自己！) 都無法知道結構的設計方式是否正確，因此會更加困難。

體驗兔耳洞

您偶爾會遇到各種行為，讓您感到驚訝或看似錯誤，應該就是這樣！請花時間找出根本原因：您會學到一些知識或完成特定工作，但這兩者都值得您花時間。因此請不要處理您不瞭解的行為。

避免重複

盡量避免重複使用程式碼。假使現有程式碼未以符合您需求的方式公開，最好將必要部分擷取到通用依附元件中。

處理錯誤

避免未處理的錯誤和 API 本質上不允許適當的錯誤處理；如需常見範例，請考慮使用 fuchsia_async::executor::spawn。spawn 原本就會排除錯誤傳遞 (因為執行流程已分割)。在多數情況下，spawn 可以替換為稍後包含在 select 運算式 (範例修訂版本) 中的未來，或直接設為 await (範例修訂版本)。

編譯時間 (以執行階段為單位)

偏好類型安全性，而非執行階段不變檢查。換句話說，請安排抽象化方式，使其無法表示無效條件，而不仰賴執行階段的斷言。

編寫可測試的程式碼；可測試的程式碼是模組化，且其依附元件很容易插入。

避免使用特定數字。

留言

撰寫留言時，請花點時間將日後的留言讀者納入考量。請確保評論中的句子完整，並且使用正確的文法和標點符號。請注意，加入更多註解或詳細註解不一定是更好的做法；例如，避免使用會使標記重覆其程式碼的註解。

說明文件註解應具有獨立性，換句話說，不要假設讀取器知道相鄰檔案或相鄰結構中的說明文件。請避免對描述類型執行個體的類型建立說明文件註解。舉例來說，AddressSet is a set of client addresses. 這個註解是用來描述 AddressSet 類型的欄位，但該類型可用於保留任何 Address，而不僅是用戶端。

撰寫註解，避免參照可能過時的參照，例如：請勿提及變數或盡可能輸入名稱 (特定文件註解是必要的例外狀況)。此外，也請避免提及過去或未來的工作內容與所記錄項目相關的過去或未來版本；解釋內容的基本原則，而非直接參照外部參照項目 (包括過去的修訂內容)。

編寫待辦事項時：

1. 請使用以下格式加入問題參考資料：TODO(https://fxbug.dev/42075402):
2. 將文字做為要採取的行動，其他協作者應該在不諮詢任何外部來源 (包括參照的問題) 的情況下，就能領取 TODO。

提供引用資料

如要實作是否遵循某些規格/文件 (例如 RFC)，請在實作時一併附上文件中相關部分的引用和引用資料。引用內容可讓讀者瞭解事件發生的原因，並藉由引述引用資料，讀者能取得更多背景資訊。

錯誤訊息

與程式碼註解一樣，請思考程式碼日後的錯誤訊息讀取者。確認您的錯誤訊息是可採取行動的。舉例來說，避免使用「意外值」之類的測試失敗訊息，一律包含非預期的值；另一個範例是「預期 <variable> 為空白，非空白」，那麼如果其中含有非預期的元素，那麼這則訊息會更加實用。

一定要考量：讀者會如何處理這則訊息？

測試

請參閱可測試性評分量表，瞭解有關 Fuchsia 測試撰寫和可測試性審查的一般指南。在 Fuchsia 網路中，我們定義了下列測試類別：

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

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

1. 一律新增測試，以發布新功能或修正錯誤。
2. 編寫測試宣告時，請考慮錯誤訊息中的指南。
3. 測試必須具有確定性。執行緒或時間相依程式碼、隨機號碼產生器 (RNG) 和跨元件通訊是非確定性的常見來源。請參閱「編寫可重現的確定性測試」一節，瞭解相關秘訣。
4. 避免使用硬式編碼逾時進行測試。偏好依賴架構/韌體來逾時測試。
5. 建議使用密封測試；測試的設定處理常式應明確且具有確定性。請注意，使用「微光」服務時，會平行執行案例的測試固件 (例如 Rust)。建議您明確插入測試所需的元件依附元件。
6. 測試應一律是元件。
7. 偏好使用虛擬裝置和網路進行非端對端測試。如需虛擬網路環境的相關指引，請參閱 netemul 的相關說明。
8. 請避免變更偵測工具測試；對變更來說，對變更極為敏感的測試 (尤其是測試中程式碼以外的測試) 可能會妨礙功能開發和重構。
9. 請勿在測試中編碼實作詳細資料，最好透過模組的公用 API 進行測試。

10. 解除包裝 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。

修訂訊息

修訂訊息應簡明但是獨立的 (避免以問題參照做為變更的說明)，並撰寫內容，以幫助日後閱讀的使用者瞭解訊息 (包括原因及任何必要背景資訊)。

避免使用大量的細節或論述。

修訂訊息應根據以下條件由簡短主旨行及獨立的說明段落組成：

1. 使用空白行將主旨和內文分隔
2. 主旨行上限為 50 個字元
3. 主旨行大寫
4. 請勿在主旨行結尾加上句號
5. 在主旨行中使用命令語氣
6. 長度為 72 個字元
7. 請使用內文說明內容、原因與方法

如果主體內容本身就明確 (例如修正錯字)，則可省略主體。Git 書籍包含「修訂指南」一節，以及許多相同的建議，以上清單是 Chris Beams 的網誌文章的一部分。

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

使用 Issue Tracker 整合時，請勿省略相關問題也可能包含的必要結構定義 (修訂訊息應簡明且獨立)。許多問題都是由 Google 內部造成，而且在讀取修訂記錄時，我們不保證所有 Issue Tracker 都可供使用。

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

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`。

程式碼審查指南

程式碼審查流程

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

作者：

• 當 CL 準備好可供審查時，請向最近 OWNERS 檔案中所列的團隊成員申請審查。
• 如果 CL 導入了重要變更，請一併新增從 src/connectivity/network/OWNERS 挑選的次要審查人員。這種情況應同時發生向擁有者要求審查的期間。您可以選擇任何團隊成員；請考慮下列條件：
  • 如果 CL 主要包含網路整合測試的變更，則在 src/connectivity/network/tests/integration/common/OWNERS 中列為可讀性審查工具。
  • 目標區域的攀升速度。
  • 在溫和相關的區域工作。
  • 有語言/模式經驗。
• 新增來自最近 OWNERS 檔案的審查者之前，您可以將 Google 群組 fuchsia-netstack-reviews@google.com 新增為評論者。gwsq 機器人會從群組隨機挑選審查者。
• 強烈建議您取得兩名審查人員的 +2，但非必要。

審查者：

• 如果您認為自己的在地知識不足，無法 +2，建議最好針對語言使用方式、樣式、模式、一般性和 +1 等方面進行審查。
• 請務必像個別審查者一樣檢查程式碼。
• 請盡可能避免委派評論的某些部分，例如「您較熟悉這個部分」。
• 無論身在當地為何，都應善用程式碼審查流程。
• 建議擁有者評論者讓次要審查人員率先通過。擁有者 +2 之後，就能產生強大的錨點影響，進而減少挑戰和學習機會。次要審查人員可以要求進行第一位通過檢查，或擁有者審查人員可藉由在 CL 中張貼一則聲明該意圖的留言，以核准第二批使用者。我們並不建議採取相反的做法，例如要求負責人先通過主通過的審查。

請注意，這項配置可能會增加審查的延遲時間，我們希望盡量減少這類問題。有人要求您審核或處理留言時，請縮短延遲時間。我們致力將作者和審查者的延遲時間維持在 24 小時內。如果偵測時間已經超過 24 小時，請不用擔心。使用 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