Changeset
為 Astro 單一儲存庫建立 changeset 檔案。Changeset 用於宣告哪些套件已更改、語意化版本提升的類型以及面向使用者的訊息，該訊息將成為 CHANGELOG 條目。
每個修改套件的 PR 都需要一個 changeset。只有 examples/* 的變更可以豁免。
建立檔案
從儲存庫根目錄執行 pnpm changeset --empty。這會在 .changeset/ 目錄中建立一個隨機命名的 .md 檔案，包含空的 front matter — 無需自行發想檔名或檢查目錄。然後編輯產生的檔案以新增套件版本提升和訊息。
格式
---
'<package-name>': patch
---
<changeset message>
- 套件名稱必須與套件
package.json中的name欄位完全相符（例如'astro'、'@astrojs/node'） - 版本提升類型：
patch、minor或major - 單一 changeset 檔案可以涵蓋多個套件
- 對核心
astro套件的major和minor版本提升會被 CI 封鎖，需要維護者審查
編寫訊息
Changeset 訊息是公開的 CHANGELOG 條目。請為 Astro 使用者 而非程式碼審查者撰寫。
以一個 現在時態的動詞 開頭，該動詞能完成句子「這個 PR ...」：
- Adds、Removes、Fixes、Updates、Refactors、Improves、Deprecates
從 Astro 網站建置者的體驗 角度描述變更，而非內部的實作方式：
// 過於專注於實作
Logs helpful errors if content is invalid
// 更好 — 使用者面向的影響
Adds logging for content collections configuration errors.
Patch 更新
通常一行就夠了。除非撰寫多個句子，否則不需要結尾標點。
---
'astro': patch
---
Fixes a bug where the toolbar audit would incorrectly flag images as above the fold
---
'astro': patch
---
Refactors internal handling of styles and scripts for content collections to improve build performance
協助讀者判斷這項變更是否與他們相關。當變更與某個可辨識的選項或函式相關時，請包含具體的 API 名稱（使用反引號格式）。當 API 不是面向使用者時，請改為描述使用案例或最終結果：
// 模糊不清
Improves automatic fallbacks generation
// 清楚 — 讀者可以判斷是否受影響
Improves automatic `fallbacks` generation for the experimental Fonts API
新功能（minor）
以「Adds」開頭，指出新 API 的名稱，並描述使用者現在可以執行什麼操作。必要時可包含程式碼範例：
---
'astro': minor
---
Adds a new, optional property `timeout` for the `client:idle` directive
This value allows you to specify a maximum time to wait, in milliseconds, before hydrating a UI framework component.
```astro
<Button client:idle={{ timeout: 500 }} />
```
新功能是撰寫更豐富描述的好機會，這些描述可用於部落格文章。有關更長條目的撰寫指南，請參閱 Astro changeset 文件。
重大變更（major）
使用如「Removes」、「Changes」或「Deprecates」等動詞。必須包含遷移指南。適當時可使用 diff 程式碼範例：
---
'astro': major
---
Removes support for Shiki custom language's `path` property. The language JSON file must now be imported and passed to the option instead.
```diff
// astro.config.js
+ import customLang from './custom.tmLanguage.json'
export default defineConfig({
markdown: {
shikiConfig: {
langs: [
- { path: './custom.tmLanguage.json' },
+ customLang,
],
},
},
})
```
對預設值的變更必須提及舊的預設值、新的預設值，以及如何恢復先前行為。
較長的 changeset
對於較長的描述，使用 #### 和更深層級的標題（切勿使用 ## 或 ###）來劃分章節。這樣可以讓你的條目在合併到 CHANGELOG 時保持可讀性：
---
'astro': minor
---
Adds a new Sessions API to store user state between requests for on-demand rendered pages.
#### Configuring session storage
<!-- ... -->
#### Using sessions
<!-- ... -->