changesets 技术详解

Changesets 的详细解释

该文档翻译已由@nnecec修订

下文将详细介绍什么是 changesets,以及它们的工作原理和思考方式。

问题:

在组织软件包的发布时,您可能会希望将由不同人编写或在相对较长时间内完成的多个更改组合在一起。捕捉这些信息的最佳时机是在提交 PR(Pull Request)时(此时信息还在你的记忆中),而不是在最终批量处理和发布这些更改时。

Git 不是一个适合存储此类信息的地方,因为它不鼓励编写详细的变更描述——您希望允许人们为每次更改提供尽可能多的文档。

解决方案, Changesets:

将 changeset 视作独立于变更日志(changelog)或版本升级之外的一种“变更意图”是最恰当的理解方式。这种变更意图包含了两个关键的信息点:

  • 版本控制
  • 变更日志

作为“变更意图”,相关的版本信息是:

  • ‘major’ | ‘minor’ | ‘patch’

此外,在多包仓库(mono-repository)中,我们可以编写关于其他需要重新发布的包的信息,以确保所有包在更新到最新版本后仍能保持兼容性。当前实现很大程度上借鉴了bolt对版本兼容性的观点。

  • 变更日志信息可以作为 Markdown 片段存储。

由于直接在 Git 中存储这类信息存在问题,因此我们使用以下结构将其存储在文件系统中:

-| .changeset/
-|-| UNIQUE_ID.md

一个 changeset 是带有 YAML 前置元数据的 Markdown 文件。Markdown 的内容是变更摘要,它会被写入变更日志;YAML 前置元数据则描述了哪些包发生了变化以及它们应该进行哪种类型的 semver 升级。

---
"@myproject/cli": major
"@myproject/core": minor
---
 
Change all the things

这种方式的好处在于它将版本控制分成了两个步骤:

  1. 添加 changeset - 可以在 PR 中由贡献者添加,当他们对更改还记忆犹新时。
  2. 版本控制 - 结合所有 changesets,根据每个包的最大版本升级创建一个版本升级,并在必要时更新依赖关系,撰写变更日志。然后可以作为一个整体进行审查。

使这一切变得有价值的工具

  1. CLI 生成新的 changesets
  2. 自动使用 changesets 进行版本控制
  3. 在 PRs 中检测并显示 changesets

用于从 monorepo 发布多个软件包的工具也很重要,但这不一定需要与上述过程相关联。

对单包仓库的好处

虽然 changesets 首先是为了处理多包仓库中的版本控制而设计的,其中理解并捕捉通过系统的内部依赖关系非常重要。

然而,从概念上讲,changesets 的好处是可以独立存在的。我认为这个过程总体上提高了 Pull Requests 的质量,有助于增强对版本控制决策和变更日志条目的信心。