Back to Details

changeset

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Changesets

Changesets

Changesets describe user-visible behavior for release notes. Root 
AGENTS.md
defines when automated contributions require one; 
CONTRIBUTING.md
is canonical for package selection, versioning, branch targets, and prose format.
Changesets 用于描述发布说明中的用户可见行为。根目录的 
AGENTS.md
定义了自动化贡献何时需要 changeset；
CONTRIBUTING.md
是选择 package、确定版本、目标分支和文案格式的权威依据。

Decide Whether One Is Required

判断是否需要 Changeset

A changeset is required for behavior visible to users of the CLI, libraries, published crates, diagnostics, parser, formatter, linter, or assists.
No changeset is needed for an internal refactor with identical behavior, tests only, CI/build maintenance, or documentation-only edits.
Before opening a PR, explicitly confirm the user-facing classification as required by 
AGENTS.md
. Do not infer user visibility only from the files changed.
如果变更会影响 CLI、library、已发布的 crate、diagnostics、parser、formatter、linter 或 assist 的用户可见行为，则需要 changeset。
如果只是行为不变的内部重构、仅修改测试、维护 CI/build 或仅修改文档，则不需要 changeset。
在创建 PR 前，必须按照 
AGENTS.md
的要求明确确认变更对用户是否可见。不要仅根据修改了哪些文件来推断用户可见性。

Choose the Release Level

选择发布级别

ChangeLevelTarget
Bug fix or non-breaking behavior correction
patch
main
New nursery lint rule
patch
main
New user-facing feature or nursery promotion
minor
next
Breaking user API change
major
next
Nursery rules are the exception to the usual new-feature mapping because they do not follow semantic versioning. Verify unusual cases against the current versioning policy.
变更级别目标分支
Bug 修复或不会破坏兼容性的行为修正
patch
main
新增 nursery lint rule
patch
main
新增用户可见功能或提升 nursery 规则等级
minor
next
破坏用户 API 兼容性的变更
major
next
nursery rule 是常规新功能映射规则的例外，因为它不遵循 semantic versioning。对于特殊情况，应根据当前版本策略进行确认。

Create the File

创建文件

Run 
just new-changeset-empty
to generate an empty file.
shell
just new-changeset-empty
An empty generated entry starts with frontmatter delimiters. Replace that frontmatter with the package and release level rather than appending a second block:
markdown
---
"@biomejs/biome": patch
---

Description.
Use 
####
or 
#####
for headings inside a longer entry. Other heading levels interfere with changelog generation.
运行 
just new-changeset-empty
生成一个空文件。
shell
just new-changeset-empty
生成的空条目以 frontmatter 分隔符开头。请将原有 frontmatter 替换为 package 和发布级别，不要再追加第二个区块：
markdown
---
"@biomejs/biome": patch
---

Description.
在较长的条目中使用 
####
或 
#####
作为标题。其他标题级别会干扰 changelog 生成。

Write the Entry

编写条目

  • Describe user-visible behavior, not implementation.
  • Use one to three sentences unless the impact genuinely needs an example.
  • Use past tense for the contribution and present tense for resulting Biome behavior.
  • Start bug fixes with the linked issue when one exists. If a link doesn't exist, start with a verb.
  • Link rule and assist names to their Biome website pages.
  • End every sentence with a full stop.
Include only the example needed to understand impact:
  • new rule: an invalid example;
  • existing rule: what became valid or invalid;
  • formatter: a 
    diff
    block;
  • parser: source that now parses or is now rejected.
Do not copy a PR summary into the changeset. A changeset is release-note text and should omit test plans, internal design, and reviewer guidance.
  • 描述用户可见的行为，而不是实现细节。
  • 除非确实需要示例来说明影响，否则使用一到三句话。
  • 贡献内容使用过去时，Biome 变更后的行为使用现在时。
  • 如果存在关联 issue，Bug 修复应以该 issue 链接开头；如果没有链接，则以动词开头。
  • 将 rule 和 assist 名称链接到对应的 Biome 网站页面。
  • 每个句子都以句号结尾。
仅包含理解影响所必需的示例：
  • 新规则：提供一个无效示例；
  • 现有规则：说明哪些内容现在有效或无效；
  • formatter：提供一个 
    diff
    区块；
  • parser：提供现在可以解析或会被拒绝的源代码。
不要将 PR 摘要复制到 changeset 中。Changeset 是发布说明文本，应省略测试计划、内部设计和 reviewer 指南。

Review Checklist

审查清单

  • The behavior is user-visible.
  • The package is correct.
  • The release level agrees with branch policy.
  • The description matches the implemented behavior.
  • Issue, rule, and assist links are accurate.
  • Examples show observable impact.
  • The file has one valid frontmatter block.
  • 变更对用户可见。
  • Package 选择正确。
  • 发布级别符合分支策略。
  • 描述与实际实现的行为一致。
  • Issue、rule 和 assist 链接准确。
  • 示例展示了可观察到的实际影响。
  • 文件中仅包含一个有效的 frontmatter 区块。

References

参考资料