為發行說明新增變更資訊

許多BeeWare工具使用towncrier來協助建立每個版本的發行紀錄。當您提交一個拉取請求給其中一個適用的工具時，它將需要包含一個變更備註 - 這個變更備註將成為發行記錄中描述所做變更的項目。

每個 pull request 必須在 changes/ 目錄中包含至少一個檔案，提供該 pull request 所執行變更的簡短說明。變更說明應該使用 Markdown 格式，檔案名稱格式為 <id>.<fragment type>.md。如果您提出的變更會修復一個 bug 或實作一個現有問題編號的功能，ID 就是該票據的編號。如果變更沒有對應的問題，則可以使用 PR 編號作為 ID。在您推送拉取請求之前，您不會知道這個 PR 編號，所以第一次 CI 傳送會無法通過 towncrier 檢查；新增變更備註並推送 PR 更新，CI 應該就會通過。

共有五種片段類型：

• 特性」：PR 增加了以前無法實現的新行為或功能（例如，增加對新封裝格式的支援，或在現有封裝格式中增加新功能）；
• bugfix：PR 修正了現有實作中的一個 bug；
• doc：PR 是對文件的重大改進；
• 刪除」； PR 代表 BeeWare 中向後不相容的變更。API; 或
• misc; 輕微或管理性的變更（例如修正錯字、輕微的語言澄清，或更新依賴版本），不需要在發行公告中公佈。

變更筆記中的描述應該是從使用者的角度對變更的高層次「行銷」摘要，而不是深入的技術描述或實作細節。它有別於提交訊息 - 提交訊息會說明已經做了什麼，以便未來的開發人員可以了解變更的原因；變更說明則是為了使用者的利益而做的說明，因為使用者可能不了解內部的情況。

例如，如果您修正了與專案命名相關的錯誤，提交訊息可能會寫成

套用更強的正則表達式檢查，禁止使用以數字開頭的專案名稱。

相應的變更備忘錄內容如下：

專案名稱不能再以數字開頭。

有些 PR 會引入多項功能並修復多個錯誤，或引入多項向後不相容的變更。在這種情況下，PR 可能有多個變更備註檔。如果需要將兩個片段類型與相同的 ID 聯繫起來，可以附加一個數字後綴。例如，如果 PR 789 增加了 ticket 123 所描述的功能，關閉了 ticket 234 所描述的錯誤，還做了兩項向後不相容的變更，您可能會有 4 個變更備註檔案：

• 123.feature.md
• 234.bugfix.md
• 789.removal.1.md
• 789.removal.2.md

更多關於 towncrier 和片段類型的資訊，請參閱 News Fragments。您也可以在 BeeWare 儲存庫的 changes 目錄中查看現有的新聞片段範例。如果這個資料夾是空的，很可能是因為 BeeWare 最近發行了新版本；每次發行時，都會刪除變更備註檔，並合併更新 release notes 。您可以查看該檔案，瞭解所需的注釋樣式；您可以查看 recently merged PRs 來瞭解變更備註的格式。