跳至主要内容

程式碼規範

本指南定義了提交至 SiMa.ai Neat 函式庫的程式碼的貢獻規則。

語言和 API 限制​

  • 使用 C++20。
  • 確保公開 API 的變更是有意且盡可能少的 (include/* 被視為穩定)。
  • 優先選擇與先前版本相容的擴展，而不是進行破壞性變更。
  • 將內部實作細節排除在已安裝/公開的標頭檔之外。

格式化和程式碼風格​

  • 使用 clang-format 執行 C/C++ 格式化（儲存庫根目錄中的 .clang-format）。
  • 使用 scripts/check_cmake_style.py 執行 CMake 程式碼風格檢查。
  • 禁止在 C/C++ 原始碼中重複包含標頭檔。
  • .editorconfig 定義了基本的空格規則（LF、最後一行換行、沒有尾隨空格）。

在推送程式碼之前，請執行：

bash scripts/check_format.sh --changed-only
bash scripts/check_cmake_format.sh --changed-only
bash scripts/check_duplicate_includes.sh --changed-only

API 相容性政策​

所有安裝在 include/* 下的標頭檔，都必須符合公開 API 的相容性要求。

  • 優先採用非破壞性新增功能（新增超載、新增選擇性欄位、新增 API）。
  • 任何破壞性簽名變更（重新命名/移除/類型變更/參數順序變更/違反行為規範）都必須在合併之前經過審查流程。
  • 如果無法避免破壞性變更，請先採用棄用期間（保留舊簽名 + 新增替代路徑），然後再移除。

破壞性 API 簽名所需流程​

在合併破壞性 API 變更之前：

  1. 在 PR 描述中的專用 Breaking API Change 區段中記錄變更。
  2. 包含影響分析：受影響的標頭檔/符號、預期的下游影響以及遷移步驟。
  3. 包含版本控制/發布意圖（何時允許發布此變更）。
  4. 在相同的變更集中更新檔案和範例，以反映新的 API。
  5. 取得對破壞性 API 介面的明確維護者批准。

模組邊界​

保持嚴格的相依性規則：

  • builder/ 不得相依於 GStreamer 或 pipeline/。
  • gst/ 不得相依於 pipeline/。
  • nodes/ 不得相依於 pipeline/。
  • pipeline/ 是協調器，可以相依於 gst/、builder/、nodes/、contracts/、policy/ 和模型內部元件。

確定性要求​

  • 對於相同的輸入/設定，節點輸出必須具有確定性。
  • 保持元件名稱的穩定性和可重現性。
  • 在可能的情況下，保留確定性管線字串生成。
  • 在變更命名行為時，請確保診斷和驗證仍然將元件映射到節點所有權。

錯誤處理和診斷​

  • 優先採用具有可操作上下文的結構化失敗。
  • 確保新的失敗路徑包含足夠的詳細資訊，以便進行 PipelineReport 診斷。
  • 避免隱藏外掛程式/caps/執行階段錯誤的靜默回退。
  • 保持診斷的執行緒安全性；探測端更新必須使用原子操作或等效的無鎖原語。

並行性和生命週期​

  • 切勿在清理路徑中無限期地阻塞。
  • 防禦性地處理執行階段狀態轉換（EOS、NULL、具有超時安全清理路徑）。
  • 保持串流執行緒邏輯的輕量化和受控的副作用。

檔案義務​

當行為發生變更時：

  • 更新 架構。
  • 如果工作流程或控制項發生變更，請更新面向使用者的指南。
  • 在參考檔案中記錄新的環境變數。

PR 品質標準​

當貢獻包含以下內容時，即表示其已準備就緒：

  • 在程式碼和提交/PR 訊息中提供明確的理由。
  • 對於新的行為和回歸進行測試。
  • 更新任何使用者可見變更的檔案。
  • 對於公開標頭檔的變更，進行 API 相容性評估（如果適用，則進行完整的破壞性變更流程）。