撰寫變更日誌

發佈 NPM 套件時，常見的做法是加入 CHANGELOG.md 檔案，以告知您的使用者有關錯誤修正、新功能以及變更或移除的功能。Rush 使用 rush change 命令自動執行此作業。此命令應在您準備好合併 PR 時執行，並在您的所有變更都已認可至分支之後執行。它會分析您分支中的變更，並（在必要時）提示您撰寫易於理解的變更描述。

您撰寫描述的方式很重要。您不希望過於簡潔或具體，您不希望洩露私人資訊，並且您希望描述盡可能地有幫助。我們建議偏向易讀性。請自問

• 「我的變更與第三方開發人員有何關聯？」
• 「這會破壞他們的程式碼嗎？」
• 「這是否修復了讓他們感到困擾的錯誤？」
• 「這是否是他們可以嘗試的新功能？」

在某些工作流程中，人類編輯者會在發佈變更日誌之前進行審閱，但是每個人都應該盡最大努力確保內容清晰且專業。

建議實務

• 使用現在簡單式，並使用祈使（「命令」）語氣。

• 從可能不熟悉您套件實作細節的外部受眾的角度來撰寫

• 著重於情境結果（「現在搜尋支援萬用字元」）而不是程式碼變更（「將規則運算式支援新增至 SearchHelper 類別」）

• 以動詞開頭。建議使用下列動詞

  • 新增 - 當您導入或公開新的功能、屬性、類別、UI 等時。
  • 移除 - 當您完全移除某個項目且該項目無法再使用時。
  • 捨棄 - 當您計畫移除某個項目，但它仍然可存取時。
  • 修復與/在...相關的問題 - 當您修正錯誤時。
  • 改善 - 當您讓現有的項目變得更好時。
  • 更新 - 當您重新整理某個項目，但不一定使其變得更好時。
  • 升級 - 當您升級相依性的版本時。
  • ... 的初始/Beta 版本 - 當發佈全新的功能時。

• 不要使用錯誤一詞。請改用問題。

• 不要使用縮寫或首字母縮寫字，除非它們廣為人知（例如「HTTP」）

• 使用正確的拼寫和文法。CHANGELOG.md 是您套件發佈的文件的一部分。

• 在提及公開 API 變更時，請使用 () 後綴來表示函式名稱，例如 setSomethingOnWebpart()

• 在提及公開 API 變更時，請在類別和屬性名稱周圍使用反引號 (` `)。

• 在記錄升級時，請指出舊版本和新版本。例如：「將 widget-library 從 1.0.2 升級到 2.0.1」

• 如果修復 GitHub 問題，請考慮在括號中加入問題 URL。

• 除非您有兩個或多個句子，否則請勿新增結尾句點。

變更日誌訊息範例

以下是一些可能提供給 rush change 的假設變更日誌訊息

• 將「buttonColor」新增至按鈕資訊清單結構描述
• 移除對 README.md 中所述舊行動網路瀏覽器的支援
• 捨棄 doSomething() API 函式。請改用 doSomethingBetter()。
• 修正「ExampleWidget」API 無法正確處理日期的問題
• 改善在進階模式下執行時的診斷記錄
• 從 React 15 升級至 React 16
• 彈性面板功能的初始版本