changeset

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Changeset

Create changeset files for the Astro monorepo. Changesets declare which packages changed, the semver bump type, and a user-facing message that becomes the CHANGELOG entry.

Every PR that modifies a package requires a changeset. Only

examples/*

changes are exempt.

为Astro monorepo创建changeset文件。Changesets用于声明哪些包发生了变更、semver版本更新类型，以及面向用户的消息（该消息将成为CHANGELOG条目）。

所有修改包的PR都需要包含changeset。仅

examples/*

目录下的变更可豁免。

Creating the File

创建文件

Run

pnpm changeset --empty

from the repo root. This creates a randomly-named

.md

file in

.changeset/

with empty front matter — no need to invent a filename or inspect the directory. Then edit the generated file to add the package bump and message.

在仓库根目录运行

pnpm changeset --empty

。这会在

.changeset/

目录下创建一个随机命名的

.md

文件，其中包含空的前置内容——无需自行指定文件名或查看目录结构。随后编辑生成的文件，添加包版本更新信息和说明消息。

Format

格式

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

<changeset message>

Package names must match the
```
name
```
field in the package's
```
package.json
```
exactly (e.g.,
```
'astro'
```
,
```
'@astrojs/node'
```
)
Bump types:
```
patch
```
,
```
minor
```
, or
```
major
```
A single changeset file can cover multiple packages
```
major
```
and
```
minor
```
bumps to the core
```
astro
```
package are blocked by CI and require maintainer review

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

<changeset message>

包名称必须与包的
```
package.json
```
中的
```
name
```
字段完全匹配（例如：
```
'astro'
```
、
```
'@astrojs/node'
```
）
版本更新类型：
```
patch
```
、
```
minor
```
或
```
major
```
单个changeset文件可涵盖多个包
核心
```
astro
```
包的
```
major
```
和
```
minor
```
版本更新会被CI拦截，需要维护者审核

Writing the Message

编写说明消息

The changeset message is a public CHANGELOG entry. Write it for Astro users, not for code reviewers.

Begin with a present tense verb that completes the sentence "This PR ...":

Adds, Removes, Fixes, Updates, Refactors, Improves, Deprecates

Describe the change as someone building an Astro site will experience it, not how it was implemented internally:

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

// Better -- user-facing impact
Adds logging for content collections configuration errors.

changeset消息是公开的CHANGELOG条目。请面向Astro用户编写，而非代码审核人员。

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

Adds、Removes、Fixes、Updates、Refactors、Improves、Deprecates

描述变更时，需从构建Astro站点的用户视角出发，而非内部实现方式：

// 过于侧重实现
当内容无效时记录有用的错误信息

// 更佳——面向用户的影响
为内容集合配置错误添加日志记录。

Patch updates

Patch更新

One line is usually enough. No end punctuation required unless writing multiple sentences.

---
'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

Help the reader figure out if the change matters to them. Include the specific API name (with backtick formatting) when the change is tied to a recognizable option or function. When the API is not user-facing, describe the use case or end result instead:

// Vague
Improves automatic fallbacks generation

// Clear -- reader can tell if it affects them
Improves automatic `fallbacks` generation for the experimental Fonts API

通常一行内容即可。除非有多句，否则无需添加结尾标点。

---
'astro': patch
---

修复工具栏审核错误将图片标记为首屏可见的问题

---
'astro': patch
---

重构内容集合的样式与脚本内部处理逻辑，以提升构建性能

帮助读者判断变更是否与他们相关。当变更涉及可识别的选项或函数时，需包含具体的API名称（使用反引号格式化）。若API不面向用户，则描述使用场景或最终结果：

// 模糊
改进自动回退生成

// 清晰——读者可判断是否受影响
为实验性Fonts API改进自动`fallbacks`生成

New features (minor)

新功能（minor）

Start with "Adds", name the new API, and describe what users can now do. Include a code example when helpful:

---
'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 }} />
```

New features are an opportunity to write a richer description that can feed into blog posts. See the Astro changeset docs for guidance on longer entries.

以“Adds”开头，指明新API，并描述用户现在可以实现的功能。必要时添加代码示例：

---
'astro': minor
---

为`client:idle`指令添加新的可选属性`timeout`

该值允许你指定UI框架组件 hydration 前的最长等待时间（以毫秒为单位）。

```astro
<Button client:idle={{ timeout: 500 }} />
```

新功能是编写更丰富描述的机会，这些描述可用于博客文章。如需编写更长条目，请参考Astro changeset文档中的指导。

Breaking changes (major)

破坏性变更（major）

Use verbs like "Removes", "Changes", or "Deprecates". Must include migration guidance. Use diff code samples when appropriate:

---
'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,
      ],
    },
  },
})
```

Changes to default values must mention the old default, the new default, and how to restore previous behavior.

使用“Removes”、“Changes”或“Deprecates”等动词。必须包含迁移指南。必要时使用diff代码示例：

---
'astro': major
---

移除对Shiki自定义语言的`path`属性的支持。现在必须导入语言JSON文件并将其传入选项中。

```diff
// astro.config.js
+ import customLang from './custom.tmLanguage.json'

export default defineConfig({
  markdown: {
    shikiConfig: {
      langs: [
-       { path: './custom.tmLanguage.json' },
+       customLang,
      ],
    },
  },
})
```

默认值变更必须提及旧默认值、新默认值，以及如何恢复之前的行为。

Longer changesets

较长的changesets

For longer descriptions, use

####

and deeper headings (never

##

###

) to divide sections. This keeps the CHANGELOG readable when your entry is incorporated:

---
'astro': minor
---

Adds a new Sessions API to store user state between requests for on-demand rendered pages.

对于较长的描述，使用

####

及更深度的标题（切勿使用

##

或

###

）划分章节。这样在你的条目被整合到CHANGELOG时，仍能保持可读性：

---
'astro': minor
---

添加新的Sessions API，用于在按需渲染页面的请求之间存储用户状态。

Configuring session storage

配置会话存储

Using sessions

使用会话

undefined

undefined