Changeset 用于为 Astro monorepo 创建变更集文件。变更集声明哪些包发生了变更、语义化版本（semver）的升级类型，以及一段面向用户的说明文字，该文字会成为 CHANGELOG 条目。
用途
凡是修改了某个包的 PR 都需要附带变更集，仅 examples/* 目录下的改动可以豁免。
创建文件
在仓库根目录运行 pnpm changeset --empty。这会在 .changeset/ 目录下创建一个随机命名的 .md 文件，其 front matter 为空——无需自行编造文件名或检查目录。随后编辑生成的文件，添加包升级类型和说明信息。
格式
'<package-name>': patch
<changeset message>
- 包名必须与包 package.json 中 name 字段完全一致（例如 'astro'、'@astrojs/node'）。
- 升级类型：patch、minor 或 major。
- 单个变更集文件可以覆盖多个包。
- 对核心 astro 包的 major 和 minor 升级会被 CI 阻止，需要维护者审查。
撰写说明信息
变更集说明信息是公开的 CHANGELOG 条目，应面向 Astro 用户撰写，而非面向代码审查者。
以现在时动词开头，补全句子“This 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.
<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.
// astro.config.js
+ import customLang from './custom.tmLanguage.json'
export default defineConfig({
markdown: {
shikiConfig: {
langs: [
- { path: './custom.tmLanguage.json' },
+ customLang,
],
},
},
})
对默认值的变更必须说明旧默认值、新默认值，以及如何恢复之前的行为。
更长的变更集
对于较长的描述，使用 #### 及更深层级的标题（绝不使用 ## 或 ###）来划分章节。这样当条目被合并进 CHANGELOG 时仍保持可读性：
'astro': minor
Adds a new Sessions API to store user state between requests for on-demand rendered pages.
Configuring session storage
<!-- ... -->
Using sessions
<!-- ... -->
适用场景
适用于 Astro monorepo 的贡献者，在提交修改了包的 PR 时创建变更集、撰写 CHANGELOG 条目或记录包变更。
限制
仅 examples/* 目录下的改动可豁免变更集。对核心 astro 包的 major 和 minor 升级会被 CI 阻止，需要维护者审查。