@wtf/release-docs 8.2.0 → 8.2.2

package/guides/ci-recipes.md

@@ -1,31 +1,48 @@
-# CI recipes
+# Run releases in CI
 
-Each train is one run of semantic-release, so CI runs one job for each train. Two rules apply to
-all CI systems:
+This page shows how to run the releases of your trains in CI, on GitLab CI and on GitHub Actions.
+Pick the recipe that matches your setup, and copy its YAML.
 
-- **One push at a time.** Each run pushes a release commit and a tag to the same branch. Two runs at
-  the same time race: the second push is rejected. Serialize the jobs.
-- **The full history.** The plugin reads the files of each commit and the tags of each train.
-  Clone with all of the history and all of the tags, not a shallow clone.
+## How a release runs in CI
 
-Give the jobs the token that semantic-release pushes with, as for any run of semantic-release:
-`GITLAB_TOKEN` on GitLab, `GITHUB_TOKEN` on GitHub.
+Each train is one run of semantic-release. CI runs semantic-release once for each train: either in
+one job per train, or in one job that runs the trains in turn. Every recipe on this page follows the
+same rules:
 
-Build before the release, in a job of its own, and give the release job what it built: the release
-runs no build. A build that generates a folder the release commits, as an API reference, lists what
-it wrote in the folder's `.generated` (`listGenerated` of `@wtf/release-trains/generated`), so the
-release stages it as built, deletions too. Nothing else runs between the plugins.
+- **One push at a time.** Each run pushes a release commit and a tag to the same branch. When two
+  runs push at the same time, the second push is rejected. Run the releases one after another.
+- **The full history.** The plugin reads the files that each commit changes, and the tags of each
+  train. Clone all of the history and all of the tags. A shallow clone does not work.
+- **A token that can push.** Give the jobs the token that semantic-release pushes with, as for any
+  semantic-release run: `GITLAB_TOKEN` on GitLab, `GITHUB_TOKEN` on GitHub.
+- **Build first.** Build in a job of its own before the release, and pass what it built to the
+  release job. The release runs no build. Nothing else runs between the plugins.
+
+Some builds generate a folder that the release commits, such as an API reference. Such a build
+lists what it wrote in the folder's `.generated` file, with `listGenerated` from
+`@wtf/release-trains/generated`. The release then stages the folder exactly as it was built,
+deletions included.
 
 ## GitLab CI
 
-A `parallel: matrix` gives one job for each train. A `resource_group` lets only one job of the group
-run at a time, so the pushes do not race. Each job fetches the branch again before it starts, and
-checks out its tip, as semantic-release releases nothing of a commit behind the tip: so it sees the
-release commit of the job before it, and a retry of a job whose publish failed runs at its own
-release commit. The tip must be the pipeline's commit with release commits alone on top: a commit
-merged since was not built, and the job stops. A release commit is known by its subject; where
-anyone may push one by hand, check what it changes too, as `git diff --quiet` of the pipeline's
-commit and the tip, of all but the changelogs and the generated folders.
+This recipe releases each train in a manual job of its own, one job at a time. Each part of the
+YAML below does one thing:
+
+1. `parallel: matrix` creates one job for each train, with `RELEASE_TRAIN` set to the train. List
+   the trains in the order of their dependencies.
+2. `resource_group: release` lets only one job of the group run at a time, so the pushes do not
+   race.
+3. `needs: [build]` gives the job what the build job built: each `dist`, and the generated folders
+   with their lists.
+4. The script fetches the branch again and checks out its tip. semantic-release releases nothing
+   from a commit that is behind the tip. On the tip, the job sees the release commit that the job
+   before it pushed. A retry of a job whose publish failed also runs at its own release commit.
+5. Before the checkout, the script checks that the tip is the pipeline's commit with only release
+   commits on top. A commit merged since then was not built, so the job stops.
+
+The check knows a release commit by its subject. If anyone can push such a commit by hand, also
+check what it changes. For example, run `git diff --quiet` between the pipeline's commit and the
+tip, on everything except the changelogs and the generated folders.
 
 ```yaml
 release:
@@ -61,8 +78,8 @@ release:
     - pnpm exec semantic-release
 ```
 
-With a JSON config, as `.releaserc.json`, which cannot write the tag format of the train, the job
-gives it on the command line, of `RELEASE_TRAIN`:
+A JSON config, such as `.releaserc.json`, cannot write the train's tag format. Pass the tag format
+on the command line instead, built from `RELEASE_TRAIN`:
 
 ```yaml
 release:
@@ -73,23 +90,36 @@ release:
     - pnpm exec semantic-release --tag-format "${RELEASE_TRAIN}-v\${version}"
 ```
 
-GitLab runs the jobs of a resource group one at a time, in no fixed order by default. When the order
-matters, set the `process_mode` of the resource group to `oldest_first` with the API
-(`PUT /projects/:id/resource_groups/release`), or write one job for each train, each with `needs:`
-on the job of the train that it depends on.
-
-The job publishes too, when the config lists the publish plugin: it packs in `prepare`, and
-publishes in the `publish` step, after the release commit and the tag are pushed. A job that fails
-there has pushed both: delete the tag on the remote and retry the job, which checks the branch out
-at the release commit and publishes what the registry lacks (see
-[Publishing](publishing.md#when-a-publish-fails)). A retry that finds the tag still on the remote
-finds the release done, publishes nothing, and passes: delete the tag first, or have the job fail
-where `git ls-remote --exit-code --tags origin` finds the tag of the train at the release commit's
-version. Of a repo of one train, a tag of the release commit, found by its hash, serves as well, of
-no tag format; not of a matrix, whose job runs at the release commit of the train before it, with
-that train's tag.
-Give the job the ID token of npm's trusted publishing, or the token of npm in an `.npmrc`, and
-Sigstore's, which npm signs the provenance by:
+### Release the trains in order
+
+GitLab runs the jobs of a resource group one at a time, but in no fixed order by default. When the
+order matters, do one of these:
+
+- Set the resource group's `process_mode` to `oldest_first` with the API
+  (`PUT /projects/:id/resource_groups/release`).
+- Write one job for each train, each with `needs:` on the job of the train that it depends on.
+
+### Publish in the release job
+
+When the config lists the publish plugin, the release job publishes too. It packs in `prepare`. It
+publishes in the `publish` step, after it has pushed the release commit and the tag.
+
+So a job that fails in `publish` has already pushed both. To finish the release:
+
+1. Delete the tag on the remote.
+2. Retry the job. It checks out the branch at the release commit, and publishes what the registry
+   does not have yet. See [Publishing](publishing.md#when-a-publish-fails).
+
+If the tag is still on the remote, the retry finds the release done. It publishes nothing and
+passes. So delete the tag first, or make the job fail when
+`git ls-remote --exit-code --tags origin` finds the train's tag for the release commit's version.
+
+In a repo with one train, you can instead look for a tag on the release commit by its hash,
+whatever the tag format. This does not work in a matrix: there, the job runs at the release commit
+of the train before it, which carries that train's tag.
+
+Give the job the ID token of npm's trusted publishing, or an npm token in an `.npmrc`. Also give it
+Sigstore's ID token: npm signs the provenance with it.
 
 ```yaml
 release:
@@ -105,25 +135,41 @@ release:
     when: script_failure
 ```
 
-### Publishing from the tag
-
-Or publish in a job of the tag's pipeline, not in the release job, by the same plugins: the release
-job's run lists no publish plugin, so it writes the changelog, commits, and pushes the tag alone,
-and the tag's job runs the plugins of the publish and of the release of the host of the tagged
-commit, as its pipeline built it. A publish that fails is then a retry of that job alone:
-semantic-release runs once a release, so the stock `@semantic-release/changelog` serves, and the
-release of the host comes after the publish, so it names no version the registry has not. The
-release job still runs at its pipeline's commit: one that fails after `@semantic-release/git` pushed
-the release commit, as of the push of the tag, cannot be retried, as the retry runs behind the
-release commit and releases nothing; finish that release by hand.
-
-semantic-release releases no tag it has, so the tag's job runs `semantic-release-trains-tag`, the
-bin of `@wtf/semantic-release-trains/tag`: semantic-release's own config, plugins and branches, of
-its run but its decision and its tag. The version is the tag's; the branch the one semantic-release
-released it on, of its note of the tag, and so its channel and dist-tag; the notes those the notes
-generator writes again of the same commits. Then `verifyConditions`, `verifyRelease`,
-`generateNotes`, `prepare`, `publish` and `success`, or `fail` of an error. It sets `RELEASE_TAG`
-before it loads the config, which gives the tag's run its plugins by it:
+### Publish from the tag pipeline
+
+You can publish in a job of the tag's pipeline instead of in the release job, with the same
+plugins. The release then happens in two parts:
+
+- The branch run lists no publish plugin. It only writes the changelog, commits, and pushes the
+  tag.
+- The tag's job runs the publish plugin and the host's release plugin on the tagged commit, as the
+  tag's pipeline built it.
+
+This has three advantages:
+
+- When a publish fails, you retry only that job.
+- semantic-release runs once for each release, so the stock `@semantic-release/changelog` works.
+- The host's release comes after the publish, so it never names a version that the registry does
+  not have.
+
+One limit remains. The release job still runs at its pipeline's commit. If it fails after
+`@semantic-release/git` pushed the release commit, for example when it pushes the tag, you cannot
+retry it. The retry runs behind the release commit and releases nothing. Finish that release by
+hand.
+
+semantic-release does not release a tag that it already has. So the tag's job runs
+`semantic-release-trains-tag`, the bin of `@wtf/semantic-release-trains/tag`. The bin uses
+semantic-release's own config, plugins and branches for the run. It only replaces semantic-release's
+decision and its tag:
+
+- The version is the tag's.
+- The branch is the one semantic-release released the tag on, read from semantic-release's note on
+  the tag. The branch sets the channel and the dist-tag.
+- The notes are written again by the notes generator, from the same commits.
+
+Then the bin runs `verifyConditions`, `verifyRelease`, `generateNotes`, `prepare`, `publish` and
+`success`, or `fail` on an error. It sets `RELEASE_TAG` before it loads the config. The config
+reads it to give the tag's run its plugins:
 
 ```js train=trains
 // release.config.mjs
@@ -166,22 +212,29 @@ publish-release:
     - pnpm exec semantic-release-trains-tag
 ```
 
-The tag is the bin's argument, else `CI_COMMIT_TAG`, or `GITHUB_REF_NAME` of a tag's run of GitHub
-Actions; `--dry-run` runs no `prepare`, `publish` or `success`, and logs the notes. A version below
-the one its dist-tag points at on npm publishes nothing (`EPUBLISHBEHIND`), so a retry of an older
-release's job, run after a newer one, moves no dist-tag back; one that npm has already is skipped.
-A channel semantic-release adds the release to later, as of a branch merged into another, pushes a
-note and no tag, so it starts no pipeline: of such branches, move the dist-tag by `tagTrain`, or by
-hand. The bin runs modules of semantic-release that are not its API, of semantic-release 25: check
-an upgrade of semantic-release with a `--dry-run` of a tag.
+What the bin does:
+
+- It takes the tag as its argument. Without one, it reads `CI_COMMIT_TAG`, or `GITHUB_REF_NAME` in
+  a GitHub Actions run for a tag.
+- With `--dry-run`, it runs no `prepare`, `publish` or `success`, and logs the notes.
+- A version below the one its dist-tag points at on npm publishes nothing (`EPUBLISHBEHIND`). So
+  when you retry an older release's job after a newer one, no dist-tag moves back. A version that
+  npm already has is skipped.
+- When semantic-release later adds a release to another channel, for example when you merge one
+  branch into another, it pushes a note and no tag. No pipeline starts. On such branches, move the
+  dist-tag with `tagTrain`, or by hand.
+- The bin runs modules of semantic-release 25 that are not semantic-release's API. Check an upgrade
+  of semantic-release with a `--dry-run` of a tag.
+
+The publish job runs in the tag's pipeline, not in the release commit's pipeline on the branch. The
+`workflow:` rule below skips the release commit's pipeline only on a branch (`$CI_COMMIT_BRANCH`). A
+tag's pipeline has no branch, so it still runs. Make the publish job `needs:` the checks of the
+tagged commit, not only the build, so that a check that fails publishes nothing.
 
-Its pipeline runs of the tag, not of the release commit on the branch: the rule below that skips
-the release commit's pipeline is of a branch alone, `$CI_COMMIT_BRANCH`, so the tag's pipeline,
-which has none, still runs. Have the publish job `needs:` the checks of the tagged commit, not the
-build alone, so a check that fails publishes nothing.
+### Skip the pipeline of a release commit
 
-The release commit of a train is `chore(release): <train> <version>`. Its pipeline on the branch has
-nothing to build, so a `workflow:` rule can skip it:
+A train's release commit has the subject `chore(release): <train> <version>`. Its pipeline on the
+branch has nothing to build, so a `workflow:` rule can skip it:
 
 ```yaml
 workflow:
@@ -191,39 +244,45 @@ workflow:
     - when: always
 ```
 
-### The semantic-release component of to-be-continuous
+### Use the to-be-continuous semantic-release component
 
 The [semantic-release component](https://gitlab.com/to-be-continuous/semantic-release) of
-to-be-continuous runs a global install of semantic-release, of no install of the repo: its
-`before_script` makes `.releaserc.json` of a `release.config.mjs`, by
-`node -pe "JSON.stringify(require('./release.config.mjs').default, null, 2)"`, then installs, by
-`npm install --global`, semantic-release and each name of `plugins` (`yq '.plugins[] | select(kind
-== "scalar") // .[0]'`), and each line of `semrel-required-plugins.txt`. The plugins of the trains
-serve it as it is:
-
-- the config is [of literals](configuring-trains.md#a-config-of-literals): `require()` takes no
-  top-level `await`, and the packages of the repo are not installed yet, so it imports nothing;
-- each plugin is a package of its own, which the install installs by the name the config gives it,
-  as many times as the config lists it, and each of its options is JSON, as the config is made
-  JSON: the plugin of the trains is one package, of an entry for each role;
-- an entry of `wrap` finds the plugin it wraps as semantic-release finds a plugin: the commit
-  analyzer and the release notes generator in the node_modules of the global semantic-release, and
-  any other beside it, of the global install; a wrapped plugin that is no dependency of
-  semantic-release, as `@semantic-release/gitlab`, is not a name of `plugins`: list it in
-  `semrel-required-plugins.txt`;
-- `@wtf/semantic-release-replace` imports a package of templates beside it, of the global install
-  too: list it in `semrel-required-plugins.txt` as well;
-- the jobs of [the pipeline of a tag](#the-pipeline-of-a-tag) install of the component too, and
-  load the plugins of the tag's run, which no run of a branch names, as
-  `@wtf/semantic-release-npm`: list each in `semrel-required-plugins.txt`;
-- the config names each ecosystem by the `./ecosystem` of its plugin, as
-  `'@wtf/semantic-release-npm/ecosystem'`, which the install of the plugin brings: the package of
-  the ecosystem, as `@wtf/release-npm`, lands in the plugin's own node_modules, where the plugin of
-  the trains does not look, so a config of that name fails with `EECOSYSTEM`.
-
-The component adds each line of the file to its `npm install` as it is, so the file holds names
-alone, with no comment. Of a plugin a wrap needs, a package of templates, as the
-`@wtf/replace-shields` of Configuring trains, and the publish of the tag's run:
+to-be-continuous installs semantic-release globally, and does not install your repo. Its
+`before_script` does three things:
+
+1. It writes `.releaserc.json` from your `release.config.mjs`, with
+   `node -pe "JSON.stringify(require('./release.config.mjs').default, null, 2)"`.
+2. It installs semantic-release and each name in `plugins` with `npm install --global`. It reads
+   the names with `yq '.plugins[] | select(kind == "scalar") // .[0]'`.
+3. It also installs each line of `semrel-required-plugins.txt`.
+
+The trains' plugins work with the component as it is. Keep these points in mind:
+
+- The config must be [a config of literals](configuring-trains.md#a-config-of-literals).
+  `require()` does not support a top-level `await`, and the repo's packages are not installed yet,
+  so the config imports nothing.
+- Each plugin is a package of its own. The install installs it by the name that the config gives
+  it, as many times as the config lists it. Each of its options must be JSON, because the config is
+  turned into JSON. The trains plugin is one package, with an entry for each role.
+- A `wrap` entry finds the plugin it wraps the way semantic-release finds a plugin. The commit
+  analyzer and the release notes generator are in the node_modules of the global semantic-release.
+  Any other wrapped plugin must sit beside it, in the global install. A wrapped plugin that is not a
+  dependency of semantic-release, such as `@semantic-release/gitlab`, is not a name in `plugins`:
+  list it in `semrel-required-plugins.txt`.
+- `@wtf/semantic-release-replace` imports a package of templates, which must also be in the global
+  install. List that package in `semrel-required-plugins.txt` too.
+- The jobs of [the tag pipeline](#build-smoke-test-and-publish-in-a-tag-pipeline) also install
+  through the component. They load the plugins of the tag's run, which no branch run names, such as
+  `@wtf/semantic-release-npm`. List each of them in `semrel-required-plugins.txt`.
+- Name each ecosystem by its plugin's `./ecosystem` export, such as
+  `'@wtf/semantic-release-npm/ecosystem'`. The plugin's install brings it. The ecosystem's own
+  package, such as `@wtf/release-npm`, lands in the plugin's own node_modules, where the trains
+  plugin does not look. A config that names that package fails with `EECOSYSTEM`.
+
+The component adds each line of the file to its `npm install` as it is. So the file holds only
+names, with no comments. This file lists a plugin that a wrap needs, a package of templates (the
+`@wtf/replace-shields` of [Configure trains](configuring-trains.md)), and the publish plugin of the
+tag's run:
 
 ```text
 @semantic-release/gitlab
@@ -231,11 +290,14 @@ alone, with no comment. Of a plugin a wrap needs, a package of templates, as the
 @wtf/semantic-release-npm
 ```
 
-One job of the component releases the trains, one run of semantic-release for each train that
-`RELEASE_TRAINS` names, in the order of the trains of the config, so one click releases them all. A train with no commit that releases
-it releases nothing and passes, and the next one runs; so a retry of the job, after a run that
-failed, passes the trains it released already, as each has nothing left to release, and goes on
-from the train that failed. Of the trains of these guides, the job releases `system`, `trains`,
+#### Release every train in one job
+
+One job of the component releases the trains. It runs semantic-release once for each train that
+`RELEASE_TRAINS` names, in the order of the config's trains, so one click releases them all.
+
+A train that has no commit to release releases nothing and passes, and the next train runs. So when
+you retry the job after a failed run, it passes the trains that it released already, and goes on
+from the train that failed. For the trains of these guides, the job releases `system`, `trains`,
 `replace`, `validate` and `docs`:
 
 ```yaml
@@ -316,33 +378,38 @@ semantic-release:
       done
 ```
 
-`RELEASE_TRAINS` is the input `release-trains` of the pipeline, a multi-select of the trains, all of
-them by default. A component of to-be-continuous maps each of its inputs to a variable, which a
-variable of the same name overrides: so a variable of the CI/CD settings, of "Run pipeline", or of
-the start of the manual job, as `RELEASE_TRAINS=docs`, names the trains instead. Whichever names
-them, and in whatever order, the job releases them in the order of the trains of the config, each
-after the trains it depends on, and fails on a name of no train.
-
-The component installs the plugins of one config, which its `before_script` makes
-`.releaserc.json` of, by the `RELEASE_TRAIN` of the job: give it the train whose run names every
-plugin that a run of any train names, so its one install serves every run. Of the config below,
-that is `docs`, whose run names the others' plugins, and the build of the reference too. The script
-removes `.releaserc.json`, which semantic-release would read before `release.config.mjs`, and runs
-each train of its own `RELEASE_TRAIN`, so each reads `release.config.mjs` again, of its own train
-and tag format.
-
-The job releases from the tip of the branch, as a run of a train pushes its release commit, which
-the run of the next train starts from, in the same job; and a retry starts behind the release
-commits of the run that failed. Its `before_script` checks out the tip only when every commit past
-the pipeline's commit is a `chore(release):` commit, which the pipeline built; of any other commit,
-it fails, and the pipeline of the tip releases it.
-
-The order is the config's to hold: with `dependencies: 'fail'` at the root, a run of `trains` or of
-`replace` fails while `system` has commits it has not released, and a run of `docs`, of
-`dependsOn`, while any train it names has. So a set out of order, or a train chosen alone, fails rather than release against
-what is not released; release the train it names first. A train whose dependency train released a
-version outside a range that its last release published releases too, of no commit of its own
-(`cascade`): a major of `system` releases `trains` and `replace` after it, in the same click. See
+Each part of the YAML does one thing:
+
+1. **Choose the trains.** `RELEASE_TRAINS` is the pipeline's input `release-trains`, a multi-select
+   of the trains, all of them by default. A to-be-continuous component maps each input to a
+   variable, and a variable of the same name overrides it. So you can also name the trains with a
+   variable in the CI/CD settings, in "Run pipeline", or when you start the manual job, such as
+   `RELEASE_TRAINS=docs`.
+2. **Install the plugins of one train.** The component's `before_script` writes `.releaserc.json`
+   from the config of the job's `RELEASE_TRAIN`, and installs that config's plugins. Give it the
+   train whose run names every plugin that any train's run names, so that one install serves every
+   run. In the config below, that train is `docs`: its run names the other trains' plugins, and the
+   build of the reference too.
+3. **Start from the tip of the branch.** Each train's run pushes its release commit, and the next
+   train's run starts from it, in the same job. A retry starts behind the release commits of the run
+   that failed. So the `before_script` checks out the tip, but only when every commit past the
+   pipeline's commit is a `chore(release):` commit, which the pipeline built. If there is any other
+   commit, the job fails, and the tip's pipeline releases it.
+4. **Release in the config's order.** The script removes `.releaserc.json`, which semantic-release
+   would read before `release.config.mjs`. It then runs each train with its own `RELEASE_TRAIN`, so
+   each run reads `release.config.mjs` again, with its own train and tag format. Whatever names the
+   trains, and in whatever order, the job releases them in the order of the config's trains, each
+   after the trains it depends on. It fails on a name that is not a train.
+
+The config keeps the order safe. With `dependencies: 'fail'` at the root, a run of `trains` or
+`replace` fails while `system` has commits that it has not released. A run of `docs` fails, through
+its `dependsOn`, while any train it names has unreleased commits. So a set out of order, or a train
+chosen alone, fails instead of releasing against what is not released. Release the train it names
+first.
+
+A train also releases with no commit of its own when a dependency train released a version outside
+a range that the train's last release published (`cascade`). For example, a major of `system`
+releases `trains` and `replace` after it, in the same click. See
 [Dependency rules](dependency-rules.md).
 
 ```js train=docs
@@ -392,29 +459,43 @@ export default {
 }
 ```
 
-The job needs `GITLAB_TOKEN`, a token that can push to the branch and create tags, which
-`CI_JOB_TOKEN` cannot, as a variable that reaches each ref it releases: a protected variable reaches
-only protected refs, so protect each branch of `branches`, and the tags of the trains by their
-patterns, `system-v*`, `trains-v*`, `replace-v*`, `validate-v*` and `docs-v*`, whose pipelines
-publish. `GITLAB_TOKEN` is such a variable, as a protected one of the group: a tag of a train left
-unprotected starts a pipeline that has no token, and its publish fails. Of a ref
-it does not reach, the run fails in `verifyConditions` (`EGITNOPERMISSION`).
+#### Give the job a token
+
+The job needs `GITLAB_TOKEN`: a token that can push to the branch and create tags. `CI_JOB_TOKEN`
+cannot. The variable must reach every ref that the job releases, and a protected variable reaches
+only protected refs. So protect:
+
+- each branch in `branches`;
+- the trains' tags, whose pipelines publish, by their patterns: `system-v*`, `trains-v*`,
+  `replace-v*`, `validate-v*` and `docs-v*`.
+
+Here `GITLAB_TOKEN` is a protected variable of the group. A train's tag that you leave unprotected
+starts a pipeline that has no token, and its publish fails. On a ref that the variable does not
+reach, the run fails in `verifyConditions` (`EGITNOPERMISSION`).
+
+#### Turn off the component's info job
 
-The component's `semantic-release-info` job, a dry run of the root of the config alone, with an
-analyzer of its own and of no train, reads every commit of the repo: leave it off (`info-on` empty,
-its default), and define the job again for every train, by `semantic-release-trains-info` (see
-[The next release of each train](#the-next-release-of-each-train)).
+The component's `semantic-release-info` job does a dry run of the config's root only, with an
+analyzer of its own and no train. So it reads every commit in the repo. Leave it off (`info-on`
+empty, its default). Define the job again for every train with `semantic-release-trains-info`
+instead: see [Predict the next release of each train](#predict-the-next-release-of-each-train).
 
-### The next release of each train
+### Predict the next release of each train
 
-A build that names its own version, in a link of its docs, a banner or a header, needs the version
+A build that prints its own version, in a link of its docs, a banner or a header, needs that version
 before the release makes it. `semantic-release-trains-info` of `@wtf/semantic-release-trains`
-decides it for every train of the config: one dry run of each, in the order of the config, as one
-click of the release job makes them. A dry run tags nothing, so the bin tags `HEAD` as each release it
-predicts, for the dry runs of the trains after it, which then see the train they depend on as
-released (no `EDEPENDENCYUNRELEASED`), and its release cascades into them by the ranges of their
-packages; it removes the tags when it is done, of a run that fails too. The config is read once of
-each train, as it reads `RELEASE_TRAIN` as it loads, so each dry run is a process of its own.
+predicts the next release of every train in the config. It does one dry run of each train, in the
+config's order, the same order that one click of the release job uses.
+
+How the bin works:
+
+- A dry run tags nothing. So the bin tags `HEAD` with each release it predicts, for the dry runs of
+  the trains after it. Those trains then see the train they depend on as released (no
+  `EDEPENDENCYUNRELEASED`), and its release cascades into them through their packages' ranges.
+- The bin removes these tags when it is done, also after a run that fails. When `SIGINT` or
+  `SIGTERM` stops it, as when the job is cancelled, it removes them before it exits.
+- The config reads `RELEASE_TRAIN` as it loads, so the bin loads it once for each train. Each dry
+  run is a process of its own.
 
 ```yaml
 semantic-release-info:
@@ -427,15 +508,17 @@ semantic-release-info:
       dotenv: semrel.out.env
 ```
 
-The bin loads the config to read its trains, and runs each train in a process of its own with
-`RELEASE_TRAIN` of that train. A config that names a train as it loads, as one whose plugins are of
-the train of the run, needs `RELEASE_TRAIN` in the job too: any train of it serves, and the run of
-each train names its own. A job that extends the component's install, which makes `.releaserc.json`
-of the config, removes it first (`rm -f .releaserc.json`), as semantic-release reads it before
-`release.config.mjs`, and each train would be decided as the train it was made of.
+The bin first loads the config to read its trains. It then runs each train in a process of its
+own, with `RELEASE_TRAIN` set to that train.
 
-The file, and the output of the bin, hold three variables of each train, its name upper-cased, each
-character that is no letter or digit an underscore:
+- If your config needs a train as it loads, for example because its plugins depend on the run's
+  train, set `RELEASE_TRAIN` in the job too. Any of its trains works: each train's run sets its own.
+- If the job extends the component's install, which writes `.releaserc.json` from the config,
+  remove that file first (`rm -f .releaserc.json`). semantic-release reads it before
+  `release.config.mjs`, so every train would be decided as the train that the file was made from.
+
+The bin writes three variables for each train, to its output and to the file. Each name holds the
+train's name in upper case, with an underscore for each character that is not a letter or a digit:
 
 ```text
 SEMREL_INFO_CORE_LAST_VERSION=1.2.0
@@ -443,35 +526,43 @@ SEMREL_INFO_CORE_NEXT_VERSION=1.3.0
 SEMREL_INFO_CORE_NEXT_VERSION_TYPE=minor
 ```
 
-A train with nothing to release has an empty next version and type, as the component's job writes
-them, so a build tells it by an empty value; its last version is the release semantic-release counts
-of the branch, so a prerelease merged into `main` is not `main`'s last. A train that has made no
-release has an empty last version. Two trains whose names make the same variables, as `a-b` and
-`a_b`, fail the bin (`EINFOVARIABLE`). Stopped by `SIGINT` or `SIGTERM`, as of a cancelled job, the
-bin removes the tags it stood in before it exits. The jobs after the job get the variables by
-`dotenv`, as the component's own, which this replaces: keep `info-on` empty, its default, so the
-component's job is off. The value is a prediction of the commit of the pipeline: a push after it, or
-a release commit of another train, can change what the release job decides.
-
-### The pipeline of a tag
-
-The pipeline of a release tag runs three jobs, and no other: `node-build` of the
-[node component](https://gitlab.com/to-be-continuous/node) builds the tagged commit,
-`release-pack-smoke` packs every train of that build and tries each package as a consumer installs
-it, and `publish-release` packs the same build and publishes it. The tagged commit passed every
-check of its branch on its way to the tag: a check run again of the tag fails after the release is
-pushed, as of a flaky test, and a retry of the pipeline runs every check again, where the retry of
-one job finishes a publish. So every other job of the pipeline, of a component or not, starts its
-`rules` with `if: $CI_COMMIT_TAG`, `when: never`; of a job of a component, the `rules` of the job
-replace the component's, so restate the component's after it.
-
-`publish-release` holds the ID tokens of npm and of Sigstore, which expire at the job's own
-`timeout`, or at 5 minutes of a job that sets none, not at the project's: a job that builds,
-smoke-tests and publishes a train of many packages runs past them, and npm answers `ENEEDAUTH`. So it
-does no more than it must: the build and the smoke run before it, in jobs that hold no token, and it
-sets a `timeout` of its own. `RELEASE_SMOKED` tells the config that `release-pack-smoke` tried the
-build already, so the tag's run of `@wtf/semantic-release-npm` packs it with no `smoke`,
-as `smoke: process.env.RELEASE_SMOKED !== 'true'`.
+- A train with nothing to release has an empty next version and type, as the component's job
+  writes them. A build can tell by the empty value.
+- The last version is the release that semantic-release counts on the branch. So a prerelease
+  merged into `main` is not `main`'s last version.
+- A train that has made no release has an empty last version.
+- If the names of two trains make the same variables, such as `a-b` and `a_b`, the bin fails
+  (`EINFOVARIABLE`).
+- The jobs after it get the variables through `dotenv`, as from the component's own job, which this
+  job replaces. Keep `info-on` empty, its default, so that the component's job stays off.
+- The values predict the release of the pipeline's commit. A push after it, or a release commit of
+  another train, can change what the release job decides.
+
+### Build, smoke-test and publish in a tag pipeline
+
+A release tag's pipeline runs three jobs, and no others:
+
+1. `node-build`, of the [node component](https://gitlab.com/to-be-continuous/node), builds the
+   tagged commit.
+2. `release-pack-smoke` packs every train from that build, and tries each package the way a
+   consumer installs it.
+3. `publish-release` packs the same build and publishes it.
+
+The tagged commit passed every check on its branch before it was tagged. A check that runs again on
+the tag can fail after the release is pushed, as a flaky test does. A retry of the pipeline then
+runs every check again, while a retry of one job is enough to finish a publish. So start the
+`rules` of every other job, from a component or not, with `if: $CI_COMMIT_TAG`, `when: never`. A
+job's `rules` replace its component's rules, so restate the component's rules after yours.
+
+Keep `publish-release` short. It holds the ID tokens of npm and Sigstore, which expire at the job's
+own `timeout`, or after 5 minutes when the job sets none. The project's timeout does not apply. A
+job that builds, smoke-tests and publishes a train of many packages runs past them, and npm answers
+`ENEEDAUTH`. So the build and the smoke test run before it, in jobs that hold no token, and
+`publish-release` sets a `timeout` of its own.
+
+`RELEASE_SMOKED` tells the config that `release-pack-smoke` already tried the build. The tag's run
+of `@wtf/semantic-release-npm` then packs it with no `smoke`, through
+`smoke: process.env.RELEASE_SMOKED !== 'true'` in the config.
 
 ```yaml
 # The build of the component, of a release tag and of no other tag. It is what the publish packs, kept
@@ -548,60 +639,82 @@ publish-release:
     - semantic-release-trains-tag
 ```
 
-`release-pack-smoke` and `publish-release` extend `.semrel-base` of the semantic-release component,
-as its `semantic-release` job does: its image, and its global install of semantic-release at the
-component's `version`, of each plugin the config names, and of each line of
-`semrel-required-plugins.txt`. So the branch's release and the tag's publish install of one source.
-The component's `before_script` reads the config of the job's environment, of no `RELEASE_TAG`, so
-it names the plugins of a run of a branch: the file names those of the tag's run, and
-`@wtf/semantic-release-npm` gives the bin `semantic-release-npm-smoke`, as
-`@wtf/semantic-release-trains` gives `semantic-release-trains-tag`. A config that needs a train as it
-loads, of `trainTagFormat`, needs `RELEASE_TRAIN` in the `variables` of each job, as the
-`semantic-release` job sets it; `semantic-release-npm-smoke` loads the config once of the
-environment of its job too, before it loads it of each train. Each job removes the
-`.releaserc.json` the install makes, which semantic-release reads before `release.config.mjs`.
-
-`publish-release` is of the
-`resource_group` of the `semantic-release` job; set the group's `process_mode` to `oldest_first`
-with the API (`PUT /projects/:id/resource_groups/release`), so the publishes of several tags run in
-the order of their tags.
-
-A publish that fails part way is finished by a retry of `publish-release` alone: it packs the build
-`node-build` keeps, and skips each package the registry has. Past the week of that build, retry
-`node-build` and `release-pack-smoke` first.
-
-### The pipeline of this repo
-
-This repo releases its packages in the trains of these guides, `system`, `trains`, `replace`,
-`validate` and `docs`, by the `semantic-release` job above, with two differences, as its own plugins are packages of
-its workspace, of versions npm may not have yet. The component's global install of the plugins is
-left out: the job installs the workspace from its lockfile, as the build does, and semantic-release
-and each plugin with it, and runs the semantic-release of the lockfile. So its `release.config.mjs`
-imports the values of `@wtf/semantic-release-trains/config` from the workspace, of what the build
-built, and is no config of literals: the component still makes `.releaserc.json` of it by
-`require()`, of the job's `RELEASE_TRAIN`, so it awaits nothing, and the job removes the file. And
-the build of the pipeline, the reference of `docs` among it, is restored over the checkout: the job
-checks out the tip of the branch, past release commits alone, without `--force`, which would put
-back the tip's reference over the one the build wrote.
-
-Its `semantic-release-info` job gives the build the next release of every train, and the build of
-`docs` its own, `SEMREL_INFO_DOCS_NEXT_VERSION`, so each source link of the reference names the tag
-`docs-v<version>` of the release that commits it. See
-[The next release of each train](#the-next-release-of-each-train). The tag's `publish-release` job runs `semantic-release-trains-tag` of the workspace, whose
-config finds the train of the tag by `trainOfTag`, and publishes the build of the tag's pipeline.
-The tags of every train, `system-v*`, `trains-v*`, `replace-v*`, `validate-v*` and `docs-v*`, are
-protected, as `GITLAB_TOKEN` is a protected variable of the group.
-
-### Skipping steps
-
-`skipPlugins` of `@wtf/semantic-release-trains/config`, of a config that imports it, leaves out each
-entry of `plugins` whose step id a pattern matches, unanchored, as of a variable a person sets as
-they start the job: the plugin's name, or of an entry of options, `<name>:<the plugin it wraps>` of
-an entry of `wrap`, `<name>:generated` of an entry of `generated`, or `<name>:<value>` of its first
-short `name`, `pkgRoot`, `path`, `tagFormat` or `train` (`stepId`). It refuses a pattern that leaves out a plugin of `required`, as
-the release commit: a tag of no release commit names a tree that does not declare the release.
-It says what it left out and what it kept by `log`, which it requires: the config, the root of
-its run, names where, as stderr.
+Notes on these jobs:
+
+- `release-pack-smoke` and `publish-release` extend the component's `.semrel-base`, as its
+  `semantic-release` job does. They get its image and its global install: semantic-release at the
+  component's `version`, each plugin that the config names, and each line of
+  `semrel-required-plugins.txt`. So the branch's release and the tag's publish install from one
+  source.
+- The component's `before_script` reads the config in the job's environment, where `RELEASE_TAG` is
+  not set. So it installs the plugins of a branch run. `semrel-required-plugins.txt` names the
+  plugins of the tag's run. `@wtf/semantic-release-npm` brings the bin `semantic-release-npm-smoke`,
+  as `@wtf/semantic-release-trains` brings `semantic-release-trains-tag`.
+- If your config needs a train as it loads, for `trainTagFormat`, set `RELEASE_TRAIN` in each job's
+  `variables`, as the `semantic-release` job does. `semantic-release-npm-smoke` also loads the
+  config once in its job's environment, before it loads it for each train.
+- Each job removes the `.releaserc.json` that the install writes, because semantic-release reads it
+  before `release.config.mjs`.
+- `publish-release` is in the `resource_group` of the `semantic-release` job. Set the group's
+  `process_mode` to `oldest_first` with the API (`PUT /projects/:id/resource_groups/release`), so
+  that the publishes of several tags run in the order of their tags.
+
+To finish a publish that failed part way, retry `publish-release` alone. It packs the build that
+`node-build` keeps, and skips each package that the registry has. After the week that the build is
+kept, retry `node-build` and `release-pack-smoke` first.
+
+### Smoke-test packages in a merge request
+
+`semantic-release-npm-smoke`, the bin of `@wtf/semantic-release-npm`, tries your packages in a merge
+request job, which releases nothing. It packs every train of the config, or each train you name with
+`--train`, from what the build wrote. Then it tries each package the way a consumer installs it, as
+the plugin's `smoke` option does in `prepare`:
+
+- It packs each train at `0.0.0-smoke.0`, a version that no registry has.
+- It packs each train with its `@wtf/semantic-release-npm` options, as the config gives them to the
+  run of its tag. To read them, it sets `RELEASE_TRAIN` and `RELEASE_TAG` in the environment of a
+  Node process of its own, which loads the config.
+- It resolves each range on another train to that train's smoke version.
+- It packs each private package in a train's `pack` beside the train's packages, as a demo.
+- It installs every package from the tarballs of all trains, and imports it, with the `forbid` of
+  the `smoke` option and the `conditions` of each entry.
+
+So a demo that would not install from the packages of its release fails the merge request, not the
+tag's pipeline. With the to-be-continuous components, this is the `release-pack-smoke` job of
+[the tag pipeline](#build-smoke-test-and-publish-in-a-tag-pipeline), which also runs in merge
+requests and on the branch. Without a component:
+
+```yaml
+smoke:
+  stage: test
+  needs: [build]
+  script:
+    - pnpm exec semantic-release-npm-smoke
+```
+
+### Skip a step when you start a job
+
+Sometimes you want to start a job without one of its steps, for example to run a release again
+whose tree is prepared already. `skipPlugins` of `@wtf/semantic-release-trains/config` does this
+in a config that imports it. It leaves out each entry of `plugins` whose step id matches a pattern. The
+pattern usually comes from a variable that a person sets when they start the job.
+
+The step id (`stepId`) of an entry is:
+
+| Entry                      | Step id                                                                               |
+| -------------------------- | ------------------------------------------------------------------------------------- |
+| A plugin's name            | The name                                                                              |
+| An entry with `wrap`       | `<name>:<the plugin it wraps>`                                                        |
+| An entry with `generated`  | `<name>:generated`                                                                    |
+| Another entry with options | `<name>:<value>` of its first short `name`, `pkgRoot`, `path`, `tagFormat` or `train` |
+
+- The pattern is unanchored: `exec` matches every step of `@semantic-release/exec`. Pin the end of
+  a short pattern with `$`.
+- `skipPlugins` refuses a pattern that leaves out a plugin listed in `required`, such as the one
+  that makes the release commit. A tag with no release commit names a tree that does not declare
+  the release.
+- It says what it left out and what it kept through `log`, which it requires. The config is the
+  root of its run, so it names where to write, such as stderr.
 
 ```js norun
 // release.config.mjs
@@ -624,33 +737,42 @@ export default {
 }
 ```
 
-### The smoke of a merge request
-
-`semantic-release-npm-smoke`, the bin of `@wtf/semantic-release-npm`, packs every train
-of the config, or each `--train` named, of what the build wrote, and tries each package as a consumer
-installs it, as the option `smoke` of the plugin does in `prepare`: a job of a merge request runs it,
-of no release. Each train is packed at `0.0.0-smoke.0`, a version no registry has, of its options of
-`@wtf/semantic-release-npm` as the config gives them the run of its tag (`RELEASE_TRAIN`
-and `RELEASE_TAG` set in the environment of a Node of its own that loads the config), each range of
-another train resolved to it, each private package of its `pack` packed beside its packages, as a
-demo, and every package installed of the tarballs of all, and imported, of its `forbid` and its
-`conditions`. So a demo that would not install of the packages of its release fails the merge
-request, not the pipeline of the tag. Of the components of to-be-continuous, it is the job
-`release-pack-smoke` of [the pipeline of a tag](#the-pipeline-of-a-tag), which runs of a merge
-request and of the branch too; of no component:
-
-```yaml
-smoke:
-  stage: test
-  needs: [build]
-  script:
-    - pnpm exec semantic-release-npm-smoke
-```
+### How this repo's pipeline differs
+
+This repo releases its packages in the trains of these guides: `system`, `trains`, `replace`,
+`validate` and `docs`. It uses the `semantic-release` job above, with two differences, because its
+own plugins are packages of its workspace, at versions that npm may not have yet:
+
+1. **No global install of the plugins.** The job installs the workspace from its lockfile, as the
+   build does, and semantic-release and each plugin with it. It runs the semantic-release of the
+   lockfile. So its `release.config.mjs` imports the values of `@wtf/semantic-release-trains/config`
+   from the workspace, as the build built them, and is not a config of literals. The component still
+   writes `.releaserc.json` from it with `require()`, for the job's `RELEASE_TRAIN`, so the config
+   awaits nothing. The job removes the file.
+2. **The build is restored over the checkout,** including the reference of `docs`. The job checks
+   out the tip of the branch, past release commits only, without `--force`. `--force` would put the
+   tip's reference back over the one that the build wrote.
+
+Its other parts:
+
+- Its `semantic-release-info` job gives the build the next release of every train. The build of
+  `docs` uses its own, `SEMREL_INFO_DOCS_NEXT_VERSION`, so each source link in the reference names
+  the tag `docs-v<version>` of the release that commits it. See
+  [Predict the next release of each train](#predict-the-next-release-of-each-train).
+- The tag's `publish-release` job runs the workspace's `semantic-release-trains-tag`. Its config
+  finds the tag's train with `trainOfTag`. The job publishes the build of the tag's pipeline.
+- The tags of every train, `system-v*`, `trains-v*`, `replace-v*`, `validate-v*` and `docs-v*`, are
+  protected, because `GITLAB_TOKEN` is a protected variable of the group.
 
 ## GitHub Actions
 
-A matrix with `max-parallel: 1` runs one train at a time, in the order of the list. A `concurrency`
-group keeps two workflows from releasing at the same time.
+This workflow releases each train in a job of its own, one train at a time:
+
+- The matrix lists the trains in the order of their dependencies. `max-parallel: 1` runs one train
+  at a time, in the order of the list.
+- The `concurrency` group keeps two workflows from releasing at the same time.
+- Each job pulls the branch first, so it starts from the release commit that the job before it
+  pushed.
 
 ```yaml
 name: release
@@ -689,7 +811,7 @@ jobs:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 ```
 
-`@semantic-release/github` makes a GitHub release of each train. List it last:
+To make a GitHub release of each train, wrap `@semantic-release/github`, and list it last:
 
 ```js train=replace
 // release.config.mjs