Back to Details

creating-changesets

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Changeset & Release Manager

Changeset 与发布管理器

Purpose

用途

Automate the creation of changesets following project conventions, ensuring proper version bumps and well-documented release notes.
按照项目约定自动创建changeset，确保版本正确升级并生成内容详实的发布说明。

When to Use

使用时机

  • After completing a feature or fix
  • Before creating a PR
  • When preparing a release
  • To document breaking changes
  • 完成功能开发或修复后
  • 创建PR之前
  • 准备发布时
  • 记录破坏性变更时

Table of Contents

目录

What is a Changeset?

什么是Changeset？

A changeset is a markdown file in the 
.changeset/
directory that describes:
  1. Which packages are affected
  2. What type of version bump (patch/minor/major)
  3. A description of the change
Changeset是
.changeset/
目录下的一个Markdown文件，用于描述：
  1. 哪些包受到影响
  2. 版本升级类型（patch/minor/major）
  3. 变更内容说明

Changeset Types

Changeset类型

TypeWhen to UseVersion Change
patch
Bug fixes, documentation, refactoring, dependency updates1.0.0 → 1.0.1
minor
New features, non-breaking enhancements1.0.0 → 1.1.0
major
Breaking changes, API modifications1.0.0 → 2.0.0
类型使用场景版本变更
patch
Bug修复、文档更新、代码重构、依赖更新1.0.0 → 1.0.1
minor
新功能、非破坏性增强1.0.0 → 1.1.0
major
破坏性变更、API修改1.0.0 → 2.0.0

Decision Guide

决策指南

Use 
patch
for:

使用
patch
的场景：

  • Bug fixes that don't change behavior
  • Documentation updates
  • Internal refactoring (no API changes)
  • Dependency updates (non-breaking)
  • Performance improvements
  • Code style/linting fixes
  • 不改变行为的Bug修复
  • 文档更新
  • 内部代码重构（无API变更）
  • 非破坏性依赖更新
  • 性能优化
  • 代码风格/语法检查修复

Use 
minor
for:

使用
minor
的场景：

  • New features
  • New CLI commands
  • New configuration options
  • Enhanced functionality
  • New entity types support
  • Non-breaking API additions
  • 新功能
  • 新CLI命令
  • 新配置选项
  • 功能增强
  • 新增实体类型支持
  • 非破坏性API新增

Use 
major
for:

使用
major
的场景：

  • Breaking configuration changes
  • Removed features or commands
  • Changed CLI interface
  • Required migration steps
  • Node.js version requirement changes
  • 破坏性配置变更
  • 移除功能或命令
  • CLI接口变更
  • 需要迁移步骤
  • Node.js版本要求变更

Creating a Changeset

创建Changeset

Interactive Method

交互式方法

bash
pnpm changeset
Follow the prompts:
  1. Select affected packages (space to select)
  2. Choose bump type for each package
  3. Write a summary of changes
bash
pnpm changeset
按照提示操作：
  1. 选择受影响的包（按空格选择）
  2. 为每个包选择升级类型
  3. 编写变更摘要

Manual Method

手动方法

Create a file in 
.changeset/
with a random name:
markdown
---
"@saleor/configurator": minor
---

Add support for reference attributes with entityType field

- Attributes of type REFERENCE now require an entityType field
- Introspection properly captures entity type references
- Deploy correctly handles reference attribute creation
在
.changeset/
目录下创建一个随机名称的文件：
markdown
---
"@saleor/configurator": minor
---

Add support for reference attributes with entityType field

- Attributes of type REFERENCE now require an entityType field
- Introspection properly captures entity type references
- Deploy correctly handles reference attribute creation

File Format

文件格式

markdown
---
"package-name": patch|minor|major
---

Short description of the change (shown in CHANGELOG)

Optional longer description with:
- Bullet points for details
- Code examples if needed
- Migration instructions for breaking changes
markdown
---
"package-name": patch|minor|major
---

Short description of the change (shown in CHANGELOG)

Optional longer description with:
- Bullet points for details
- Code examples if needed
- Migration instructions for breaking changes

Release Workflow

发布流程

1. Create Changeset

1. 创建Changeset

bash
pnpm changeset
git add .changeset/
git commit -m "chore: add changeset for feature"
bash
pnpm changeset
git add .changeset/
git commit -m "chore: add changeset for feature"

2. PR and Review

2. PR与评审

  • Changeset is part of the PR
  • Reviewers can suggest bump type changes
  • Changeset是PR的一部分
  • 评审人员可以建议修改升级类型

3. Merge to Main

3. 合并到主分支

  • Changesets action creates "Version Packages" PR
  • This PR updates version and CHANGELOG
  • Changesets动作会创建“Version Packages” PR
  • 该PR会更新版本号和CHANGELOG

4. Merge Version PR

4. 合并版本PR

  • Triggers npm publish
  • Creates GitHub release
  • 触发npm发布
  • 创建GitHub发布

Checking Status

状态检查

bash
undefined
bash
undefined

See what changesets exist

查看现有changeset

npx changeset status
npx changeset status

Preview version bump

预览版本升级

npx changeset version --dry-run
undefined
npx changeset version --dry-run
undefined

Common Mistakes

常见错误

MistakeIssueFix
Wrong bump typeUnexpected versionReview decision guide above
Vague descriptionPoor CHANGELOGBe specific about changes
Missing changesetNo release notesAlways add before PR
Multiple changesetsFragmented notesCombine related changes
Not including contextHard to understandExplain why not just what
错误问题修复方案
错误的升级类型版本不符合预期参考上方的决策指南
模糊的描述变更日志质量差具体描述变更内容
缺少changeset无发布说明提交PR前务必添加
多个零散的changeset变更说明碎片化合并相关变更的changeset
未包含上下文难以理解变更原因不仅说明“做了什么”，还要说明“为什么做”

Common Scenarios

常见场景

For detailed examples of common scenarios including:
  • Bug fixes, new features, breaking changes
  • Multiple related changes
  • Consolidated changesets
  • Pre-release versions
  • Best practices for descriptions
See Scenarios & Examples
关于以下常见场景的详细示例：
  • Bug修复、新功能、破坏性变更
  • 多个相关变更
  • 合并后的changeset
  • 预发布版本
  • 描述的最佳实践
请查看**场景与示例**

References

参考资料

Related Skills

相关技能

  • CI/CD automation: See 
    managing-github-ci
    for release workflow integration
  • Pre-commit validation: See 
    validating-pre-commit
    for quality gates before committing
  • CI/CD自动化：请查看
    managing-github-ci
    了解发布流程集成
  • 提交前验证：请查看
    validating-pre-commit
    了解提交前的质量检查