撰寫良好的提取要求

提取要求就像是存放區的生命線,讓一切運作順暢無虞。本頁面將詳細說明如何建立完整且易於審查的提交要求,提高提交要求合併的可能性。

以下是確保能建立最佳公關的步驟。

  1. 通訊
  2. 進行設定
  3. 保持小巧
  4. 保持清潔
  5. 測試變更
  6. 溝通 (第 2 部分)

通訊

在您開始撰寫程式碼之前,建議您與核心團隊進行溝通,讓他們瞭解您的興趣所在。

如果有您感興趣的問題,請在該問題上留言,表示您將開始著手處理。這樣一來,就能確保不會有多人同時處理同一件事情。團隊成員會回覆,確認該裝置屬於你。

如果您有想法,但未涵蓋在任何問題中,請在開始工作前撰寫一篇文章。這樣一來,團隊就能在您開始建構前討論如何最佳化變更作業,從長遠來看可節省您的工作量。

進行設定

如果這是您首次為 Blockly 或 Blockly 範例提供意見,請先參閱「開發設定」頁面。

保持小型

請務必盡量減少變更項目,並專注於特定項目。我們寧願審查多項較小的 PR,而非審查一項大型 PR。以下是一些實用經驗法則:

  • 修正一個問題。請勿一次處理多個問題。
  • 限制範圍。通常 PR 應在 8 小時內完成 (視您對程式碼集的熟悉程度而定)。
  • 使用提交。如果覺得提交要求有點大,請使用 Git 提交將變更項目分成邏輯群組。

保持清潔

為什麼要重視程式碼樣式?我們會長期提供這項服務,而一致的樣式有助於簡化維護作業。樣式是指變數命名方式,但也涵蓋程式碼結構、註解編寫方式等。我們會盡可能使用 eslint 等工具,自動執行樣式檢查。

除了 eslint 外,請遵循下列指南:

測試變更

在提交合併請求之前,請務必測試變更是否正常運作,以免日後需要回頭修正。以下提供一些測試不同類別專案的想法:

  • 外掛程式:編寫涵蓋變更的自動化 Mocha 測試。
  • 示例:手動測試所有展示的功能。
  • codelabs:在乾淨的環境中執行整個教學課程,並測試您提供的任何程式碼範例。

通訊

這是建立 PR 的最後步驟,也是最重要的步驟:撰寫摘要。

撰寫優質的提交要求摘要,有助於其他開發人員審查您的變更,進而提高變更通過的機率!

摘要應包含以下內容:

  • 與您的提交內容相關的問題。
  • 變更要求 (PR) 新增的內容。
  • 如何測試變更。
  • 任何你想讓審查員仔細審查的內容。
  • 任何你認為審查人員需要的其他資訊。

只要您在建立要求時遵循 PR 範本,應該就沒問題。請記得盡可能保持簡潔完整

祝您程式設計一切順利!