changeset

Changeset

为 Astro monorepo 创建 changeset 文件。Changeset 会声明发生变更的包、SemVer 升级类型，以及将作为 CHANGELOG 条目的面向用户的说明。

每个修改了包的 PR 都需要 changeset。只有 examples/* 的变更可以豁免。

创建文件

在仓库根目录运行 pnpm changeset --empty。这会在 .changeset/ 中创建一个随机命名、包含空 front matter 的 .md 文件——无需自行编造文件名，也无需检查目录。然后编辑生成的文件，添加包升级类型和说明。

格式

---
'<package-name>': patch
---

<changeset message>

• 包名必须与包的 package.json 中的 name 字段完全一致（例如，'astro'、'@astrojs/node'）
• 升级类型：patch、minor 或 major
• 单个 changeset 文件可以涵盖多个包
• 对核心 astro 包进行 major 和 minor 升级会被 CI 阻止，且需要维护者审核

撰写说明

Changeset 说明是一条公开的 CHANGELOG 条目。请面向 Astro 用户 撰写，而不是面向代码审查者。

以一个现在时动词开头，补全句子“This PR ...”：

• Adds（新增）、Removes（移除）、Fixes（修复）、Updates（更新）、Refactors（重构）、Improves（改进）、Deprecates（弃用）

从构建 Astro 网站的用户会如何体验此变更的角度描述，而不是说明内部如何实现：

// Too implementation-focused
Logs helpful errors if content is invalid

// Better -- user-facing impact
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 不面向用户，请改为描述使用场景或最终效果：

// Vague
Improves automatic fallbacks generation

// Clear -- reader can tell if it affects them
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