发布管理流程

pnpm 无需额外的发布工具,就能独立完成工作区的版本管理与发布。这套工作流分为两步:

  1. As you work, pnpm change records change intents: small markdown files in .changeset/ saying which packages a change affects, how each should be bumped, and a summary that becomes the changelog entry. 它们会与变更一同提交。
  2. 发布时,直接执行 pnpm version -r 即可消耗这些待处理意图:它会提升整个工作区内的版本、传播给依赖方、写入变更日志,并把所消耗的内容记入纳入提交的账本。

意图文件采用 changesets 格式,因此现有的 .changeset/ 目录可以继续沿用。如果你希望继续使用 Changesets CLI,请参阅在 pnpm 中使用 Changesets。

记录变更项#

pnpm change

该命令会提示输入受影响的包、各包的提升类型与摘要,随后写入类似 .changeset/calm-cats-resolve.md 的文件:

.changeset/calm-cats-resolve.md
---
"@example/core": minor
---

Added a `--watch` flag to the build command.

若想预览这些待处理意图会产生什么结果:

pnpm change status

发布#

pnpm version -r

该命令会执行发布计划:凡被某个意图点名的包都会提升版本,通过 workspace: 范围依赖它的包同样如此。建议先用 --dry-run 预览,并用 --filter 缩小处理范围。

Because a recursive run can bump many packages to different versions, no git commit or tag is created, because there is no single version to tag. 结果需要你自行提交,随后用 pnpm publish -r 发布。

首个版本发布#

The first release of a package publishes the version written in its manifest verbatim. pnpm version -r 和 pnpm change status 会为每次发布向注册源查询当前版本;如果该版本还没发布,包就以该版本首次发布,待处理的变更意图只会在下一次发布时生效。于是,新加入的包若初始版本为 1100.0.0 且带一条 minor 意图,会以 1100.0.0 发布,而不是直接跳到 1100.1.0。

Private packages ("private": true) are never published, so they skip this registry check: their pending change intents are always applied on top of the version in their manifest.

配置#

发布行为在 pnpm-workspace.yaml 的 versioning 键下配置:

pnpm-workspace.yaml
versioning:
  fixed:
    - ['@example/cli', '@example/napi']
  ignore:
    - '@example/internal'
  maxBump: minor
  lanes:
    '@example/cli': alpha
  changelog:
    storage: repository

各项键的说明见版本管理设置。

当两个工作区项目发布相同名称时,可以用带 ./ 前缀的工作区相对目录引用项目,而无需使用其名称(例如 "./packages/cli")。工作空间该写法在意图文件以及 versioning.lanes、versioning.fixed 和 versioning.ignore 中都可用。

固定组#

Packages listed together in versioning.fixed always release at one shared version: the highest current version in the group, bumped by the largest bump any member needs. 固定组必须整体在通道之间迁移,并且要么完全在某个 epic 之内,要么完全在其之外。

通道#

通道是一条并行的发布轨道。包在通道上时,会在发布主通道全部稳定版本的同一批运行中,产出 X.Y.Z-<lane>.N 形式的预发布版本。这样可以让重写或某个主版本线在公开环境中逐步成熟,同时工作区其余部分继续正常发布。

pnpm lane alpha --filter @example/cli   # 切换到 alpha 通道
pnpm lane main --filter @example/cli    # 回归稳定通道
pnpm lane                               # 显示成员

预发布版本如何计算,参见 pnpm lane。

剧集#

An epic ties a group of member packages to a lead package, constraining every member's major version to a band derived from the lead's major: while the lead is on major M, members live in M*100 to M*100+99.

pnpm-workspace.yaml
versioning:
  epics:
    - lead: '@example/app'
      packages:
        - './packages/**'
        - '!./packages/private-*'

With the lead on 11.x, members occupy majors 1100 to 1199. Members move independently inside the band: patch, minor, and even a major intent that stays in-band. 会让成员越过区间上限的提升会被拒绝,直至主导包推进自身主版本。当发布计划把主导包带到新的稳定主版本时,所有成员都会在同一计划中重新落到区间下限。

成员资格通过 pnpm 的包选择器匹配:名称通配符、带 ./ 前缀的目录通配符,以及带 ! 前缀的否定项。选择器按顺序求值,由最后一个匹配项决定,因此后续的包含项可以重新纳入先前被否定项排除的包。主导包永远不会成为自身区间的成员。

Checking committed versions#

pnpm change check validates the versions already committed in the workspace against the versioning.epics bands and the versioning.fixed groups, without reading any change intent. Run it in CI, next to the lint and test steps, so a version that drifted out of its band is caught on the pull request that introduced it rather than at release time.

变更日志#

默认(versioning.changelog.storage: registry)不会提交任何 CHANGELOG.md。每次发布的章节会在发布时生成,并叠加到上一已发布版本的变更日志之上,一同打包进已发布的 tarball 中。只有在注册源确认该版本已连同其章节一起发布之后,已消耗的变更意图才会被后续的 pnpm version -r 回收。

改为设置 versioning.changelog.storage: repository,即可在每个包中保留已提交的 CHANGELOG.md 文件。

Release notes on pnpr#

When a package publishes to a registry declared with serverType: pnpr, registry storage stores its section, without its version heading, as the version's release notes instead of packing it into the tarball. The packages of a release plan that publish to such a registry form one release:

  • An intent that names only one of them goes into that package's notes.
  • An intent that names several of them goes once into the notes of the release, with the packages it applies to.
  • An intent that also names a package outside the release stays in the notes of every package it names.

The release is named v<version> after the version of its epic lead, or of its one fixed group. pnpm publish -r --batch sends the whole release in one request. pnpm version -r --release-notes <file> adds a summary written by hand above the notes of the release, or above the package's notes when the release has one package, and pnpm publish --publication-name names the release. Every note is composed by pnpm version -r and kept until publish, so pnpm publish takes no --release-notes for these packages. A release with a name or notes of its own reaches one registry, so pnpm version -r refuses one whose packages publish to several pnpr registries before it changes any version; version the packages of each registry on their own with --filter.

Nothing is packed into or fetched from a tarball. A later pnpm version -r deletes consumed intents once the registry holds the notes composed from them: each note either still contains that text, or was created from it, which the registry proves with the note's initial digest after an edit.

Private packages are never published, so no tarball could carry their changelog. Their releases always use repository storage, whatever is configured: the section is prepended to the package's committed CHANGELOG.md, and the release counts as consumed without a registry confirmation. An intent file that also names other projects is still deleted only once all of them have released.

账本#

pnpm version -r 会把每个已消耗的意图记录到 .changeset/ledger.yaml 中,这是一个纳入提交、仅追加的文件:

.changeset/ledger.yaml
"@example/core@1.3.0":
  dir: packages/core
  intents:
    - calm-cats-resolve

消耗情况按项目跟踪:只有当某个意图文件点名的每个项目都已发布后,该文件才会被删除。 This is what makes cherry-picks and merge-backs between release branches safe. A release branch that has already consumed an intent will not consume it again when the commit is merged forward, and a package on a lane can half-consume an intent whose prose still has a stable release to compose.