@wtf/release-docs 8.2.0 → 8.2.2

package/guides/publishing.md

@@ -1,92 +1,24 @@
-# Publishing
-
-The stock `@semantic-release/npm` publishes one package in a run. A train often has several.
-`@wtf/semantic-release-npm` publishes every npm package of the train in one run, in the order of
-their dependencies, by `@wtf/release-npm`, the library, and writes no file of the repo. The library
-is the ecosystem of npm too, its default export, which the plugin exports at `./ecosystem` and a
-config names in `ecosystems` as `'@wtf/semantic-release-npm/ecosystem'`, so the trains read the packages of each `package.json` by it. The version of a release is its tag's: each `package.json` in git keeps a placeholder, as
-`0.0.0-development`, and the release commit holds no version.
-
-1. **The manifests**, `resolveManifests`. The packages of the train that publish, every package under
-   its paths that is not private, found as the package manager finds them, by the globs of
-   `pnpm-workspace.yaml` or of the `workspaces` of `package.json`, and ordered: each after the
-   packages that it runs with. `first` and `last` pin a package to an end. Each manifest as it
-   publishes: the version of the release; each `workspace:` range of a package of the train
-   resolved to that version, as pnpm resolves `workspace:*`, `workspace:^` and `workspace:~`; of a
-   package of another train, to the last release of that train, by its tags (`releasedVersions` of
-   `@wtf/release-trains/packages`, and `resolveSpecifier` of `@wtf/release-npm/manifests`, which
-   the cascade of a train reads too); each devDependency by
-   a `workspace:` range of a package that no train releases, as a private package of shared
-   configs, or of a train with no release yet, dropped, as no consumer installs it; each export of the source stripped (the `source`
-   condition, or a `.ts` target). Then each checked. It writes nothing.
-2. **The tarballs**, `packTrain`. Each package copied, but its `node_modules`, into a folder of the
-   system's temporary files, its manifest written into the copy, and each packed there, all before
-   the first publish. A fault stops the run before anything is on the registry.
-3. **The publish**, `publishTrain`. Each package under the dist-tag of the channel of the release
-   (`latest`, or `beta` of `2.1.0-beta.3`, or `prerelease` of `2.1.0-0`; `release-1.x` of a channel
-   npm takes for a range, as `1.x` of a branch of maintenance), with provenance where the CI gives
-   an ID token. Each version that the registry already has is skipped. Before the first, the
-   registry is asked of each (`publishedOf`): a package it has not, whose dist-tag points above
-   the release, fails the run, and nothing is published (`EPUBLISHBEHIND`), as it would move the
-   dist-tag back. A prerelease on `latest`, where npm points it at the first version of a package,
-   is not above a release. A package named in `aside`, as one that joined the train at a higher
-   version of its own, is published under the dist-tag of its major's line instead,
-   `release-<major>.x` of `latest`, and its dist-tag stays; unless that dist-tag points above the
-   release too. A release on a channel of a line already, as `release-1.x` or `release-1.2.x` of
-   maintenance, puts nothing aside.
-
-The plugin takes the steps of `@semantic-release/npm`:
+# Publish npm packages
 
-- `verifyConditions` checks the publisher and the packages as they are in the repo.
-- `prepare` does steps 1 and 2, and asks the registry, before the tag: a range that no release
-  satisfies (`EDEPENDENCYUNSATISFIED`), a train it needs with no release (`EDEPENDENCYNORELEASE`),
-  a package of no train it needs (`EDEPENDENCYNOTRAIN`), a package that cannot be packed,
-  or a release that would move a dist-tag back (`EPUBLISHBEHIND`), fails here.
-- `publish` does step 3 with what `prepare` packed, after the tag is pushed, and gives
-  semantic-release the release as the stock plugin does: the name of the publisher and its
-  packages, the page of the first package, and the channel. Then it removes the copies, and the
-  tarballs but of a `tarballDir` it is given, which keeps them. A run whose `publish` finds nothing
-  packed of its train and version, in the same process, resolves and packs again.
-- `addChannel` moves a release that is published already to the dist-tag of its new channel, by
-  `tagTrain`, as semantic-release asks when a branch of one channel is merged into the branch of
-  another: each package of the train the registry has at the version, by `npm dist-tag add` of
-  either publisher built in. npm moves a dist-tag by the token of its config alone: its trusted
-  publishing covers `npm publish` and no other command, so a release from a branch of a channel
-  needs `NPM_TOKEN` too. A publisher of your own moves dist-tags by its `tag` step; one without it
-  moves none. semantic-release records the new channel before it asks for `addChannel`, so a run
-  again moves nothing: move a dist-tag that failed by hand, as its error says.
-
-The release of the host is not this plugin's. List `@semantic-release/gitlab` or
-`@semantic-release/github` after it.
+`@wtf/semantic-release-npm` publishes every npm package in a train in one run. Use it in place of
+the stock `@semantic-release/npm`, which publishes one package per run, when a train holds several
+packages. The plugin publishes the packages in dependency order and does not write any file in your
+repo.
+
+The version comes from the tag. Each `package.json` in git keeps a placeholder version, such as
+`0.0.0-development`, and the release commit holds no version. The plugin writes the version into a
+copy of each package when it packs it.
 
-### When a publish fails
-
-Of a publish in the pipeline of the tag, by `semantic-release-trains-tag`, retry the job that
-publishes, and keep the tag: the retry packs the build of the tagged commit again, skips each package
-the registry has, and publishes the rest (see
-[the pipeline of a tag](ci-recipes.md#the-pipeline-of-a-tag)). Delete no tag and run no release of
-the branch again: of a release whose config names no publish plugin, that run commits a second
-release commit, of the same version, its changelog written again by the stock
-`@semantic-release/changelog`, and tags it, a commit the pipeline of the first tag did not build.
-
-Of a publish in the release run itself, as below, semantic-release pushes the release commit of
-`@semantic-release/git`, and the tag, before it runs `publish`, as it does for every plugin. A
-publish that fails part way leaves both, and a run again
-finds that version released and does nothing. To finish it, delete the tag, on the remote and in the
-clone that runs again (a tag of the clone is a release done too), and run the release again at the release commit, the tip of the branch: semantic-release releases nothing
-of a commit behind the tip. The run computes the same version, tags the release commit, skips each
-package that the registry already has, publishes the rest, and makes the release of the host. A
-changelog plugin the trains plugin wraps finds the section of the release in the changelog already
-and skips its `prepare`, so `@semantic-release/git` finds nothing to commit. Listed unwrapped,
-`@semantic-release/changelog` writes the section again: wrap it, or remove the second section
-before the run.
-
-A retry of a job that runs at the commit of its pipeline, as a job of to-be-continuous does, runs
-behind the release commit. Check the tip out first, where it is the pipeline's commit with release
-commits alone on top: see [CI recipes](ci-recipes.md#gitlab-ci).
+The plugin runs on a library, `@wtf/release-npm`. The library's default export is the npm
+ecosystem, and the plugin exports the same ecosystem at `./ecosystem`. Add
+`'@wtf/semantic-release-npm/ecosystem'` to `ecosystems` in your config so that the trains can find
+the packages in each `package.json`. [How ecosystems work](ecosystems.md) explains what an
+ecosystem does.
 
 ## Turn it on
 
+Add the plugin to your config, after the trains plugin:
+
 ```js train=trains
 // release.config.mjs
 import { trainTagFormat } from '@wtf/semantic-release-trains/config'
@@ -109,63 +41,225 @@ export default {
 }
 ```
 
-| Option       | Default                         | What it is                                                                                                                                                           |
-| ------------ | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `publisher`  | `npm`                           | `npm`, `pnpm`, the path of a module, or a package. See below.                                                                                                        |
-| `access`     | each `publishConfig.access`     | `public` or `restricted`.                                                                                                                                            |
-| `provenance` | `auto`                          | With provenance: `auto` when the CI gives an ID token, or `true`, or `false`.                                                                                        |
-| `registry`   | each `publishConfig.registry`   | The registry.                                                                                                                                                        |
-| `first`      | none                            | The folder of the package that publishes first.                                                                                                                      |
-| `last`       | none                            | The folder of the package that publishes last.                                                                                                                       |
-| `conditions` | `['source']`                    | The export conditions of the source, which no tarball ships.                                                                                                         |
-| `check`      | `true`                          | Check the packages before the first publish.                                                                                                                         |
-| `aside`      | none                            | The packages, by name, published under `release-<major>.x` of `latest`, `<dist-tag>-<major>.x` of another, where their dist-tag points above the release.            |
-| `tarballDir` | of the system's temporary files | The folder of the tarballs, kept after the release, as assets of the release of the host; one in the repo is for git to ignore, and a job of the CI starts it empty. |
-| `pack`       | none                            | Folders or globs of private packages of the train, packed beside the others into `tarballDir`, never published: as a demo, an asset of the release of the host.      |
-| `distTag`    | the channel's                   | The dist-tag every package is published under, over the channel's, as a one-off; an empty one is none.                                                               |
-| `smoke`      | `false`                         | `true`, or `{ forbid }` of globs no tarball may hold: each package packed tried as a consumer installs it, in `prepare`, before the tag. See below.                  |
-
-`provenance: 'auto'` looks for an ID token npm signs the provenance by: `SIGSTORE_ID_TOKEN` (GitLab,
-of the audience `sigstore`), or the OIDC of GitHub Actions. `NPM_ID_TOKEN`, of npm's trusted
-publishing on GitLab, signs nothing: give a GitLab job both, or npm fails `--provenance`. On a
-runner the CI does not host, `CI_RUNNER_ENVIRONMENT` (GitLab) or `RUNNER_ENVIRONMENT` (GitHub) of
-`self-hosted`, it publishes with none: npm refuses provenance, and trusted publishing, of such a
-runner, so it publishes by a token of npm there.
-
-A package of `pack` is packed of its manifest as it publishes too: of the version of the release,
-and each `workspace:` range of a private package of the workspace resolved to it. `distTag` of an
-environment variable a job sets, as `distTag: process.env.NPM_DIST_TAG`, writes `undefined` when it
-is unset, which JSON leaves out: the channel's then.
-
-### The smoke
-
-A workspace and its tests resolve each package of its source, and see neither a file its tarball
-misses, nor an export that imports a peer its consumer has not installed. Of `smoke`, `prepare` tries
-each package it packed as a consumer installs it, each private package of `pack` too, before the tag,
-by `smokePacked` of `@wtf/release-npm/smoke`, and fails the run with `EPUBLISHSMOKE` of
-every fault it finds:
-
-- of the tarball: an entry of its `files` it holds not, as of a package packed of no build; an export
-  of a condition of the source; a file of `forbid`, as `**/*.tsbuildinfo`;
-- of its install by npm, in a project of its own in the system's temporary files, every other package
-  packed installed of its tarball by npm's `overrides`, so none is asked of the registry;
-- of an import of each entry of its `exports`, but `./package.json` and a pattern: a `SyntaxError`, a
-  module not found that is no optional peer of the manifest, nor a specifier of a bundler's own, and
-  an export a packed package does not export. Any other error of an import is the module's to throw.
-  A package of no `exports` and no `main`, as a demo of static files, has no entry to import: it is
-  installed alone.
-
-It needs `tar`, `npm` and `node` where it runs. A job that runs no release, as of a merge request,
-runs it of every train by the bin of the plugin: see [CI recipes](ci-recipes.md#the-smoke-of-a-merge-request).
-A pipeline whose job of the bin runs before its publish job, as
-[the pipeline of a tag](ci-recipes.md#the-pipeline-of-a-tag) of to-be-continuous, turns `smoke` off
-in the tag's run, of a variable the publish job sets, so the job that holds the ID tokens does no
-more than publish.
-
-## As a library
-
-The three steps are functions of `@wtf/release-npm/release`, of no release tool, each by
-the `system` its caller gives it, as a CLI passes its own, adapted to the interface:
+The plugin does not create the release on GitLab or GitHub. List `@semantic-release/gitlab` or
+`@semantic-release/github` after it.
+
+| Option       | Default                                  | What it does                                                                                                                                                                                                         |
+| ------------ | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `publisher`  | `npm`                                    | The tool that publishes: `npm`, `pnpm`, the path of a module, or a package name. See [Publishers](#publishers).                                                                                                      |
+| `access`     | each package's `publishConfig.access`    | `public` or `restricted`.                                                                                                                                                                                            |
+| `provenance` | `auto`                                   | Whether to publish with provenance: `auto` (when the CI provides an ID token), `true` or `false`.                                                                                                                    |
+| `registry`   | each package's `publishConfig.registry`  | The registry to publish to.                                                                                                                                                                                          |
+| `first`      | none                                     | The folder of the package to publish first.                                                                                                                                                                          |
+| `last`       | none                                     | The folder of the package to publish last.                                                                                                                                                                           |
+| `conditions` | `['source']`                             | The export conditions that point at source files. No tarball ships them.                                                                                                                                             |
+| `check`      | `true`                                   | Check the packages before the first publish. See [What the check catches](#what-the-check-catches).                                                                                                                  |
+| `aside`      | none                                     | Package names to publish under their major's line when their dist-tag points above the release: `release-<major>.x` in place of `latest`, `<dist-tag>-<major>.x` in place of another.                                |
+| `tarballDir` | a folder in the system's temporary files | Where to keep the tarballs after the release, for example as assets of the GitLab or GitHub release. Add a folder in the repo to `.gitignore`. A CI job starts with it empty.                                        |
+| `pack`       | none                                     | Folders or globs of private packages in the train. The plugin packs them into `tarballDir` beside the others and never publishes them. Use it for a demo or another release asset.                                   |
+| `distTag`    | the channel's                            | One dist-tag for every package, in place of the channel's, for a one-off release. An empty string means no override.                                                                                                 |
+| `smoke`      | `false`                                  | `true`, or `{ forbid }` with globs that no tarball may hold. Installs each packed package as a consumer would, in `prepare`, before the tag. See [Smoke-test the packages](#smoke-test-the-packages-before-the-tag). |
+
+### Provenance
+
+With `provenance: 'auto'`, the plugin looks for an ID token that npm can sign the provenance with:
+
+- `SIGSTORE_ID_TOKEN` on GitLab, with the audience `sigstore`;
+- the OIDC token of GitHub Actions.
+
+`NPM_ID_TOKEN`, which npm's trusted publishing uses on GitLab, does not sign anything. Give a GitLab
+job both tokens, or npm fails `--provenance`.
+
+On a self-hosted runner, the plugin publishes without provenance. It detects one when
+`CI_RUNNER_ENVIRONMENT` (GitLab) or `RUNNER_ENVIRONMENT` (GitHub) is `self-hosted`. npm refuses
+provenance and trusted publishing from such a runner, so publish with an npm token there.
+
+### Packages in `pack`, and `distTag` from a variable
+
+The plugin packs a package in `pack` with its manifest resolved as for a publish. The manifest gets
+the release's version, and each `workspace:` range on a private package of the workspace resolves
+to that version.
+
+You can set `distTag` from an environment variable that a job sets, as
+`distTag: process.env.NPM_DIST_TAG`. When the variable is unset, the value is `undefined`, which
+JSON leaves out, and the channel's dist-tag applies.
+
+## What a release does
+
+A release runs three steps. Each step is a function of `@wtf/release-npm/release`.
+
+1. **Resolve the manifests** (`resolveManifests`). The plugin finds the train's packages that
+   publish: every package under the train's `paths` that is not private. It finds them the way the
+   package manager does, by the globs in `pnpm-workspace.yaml` or in the `workspaces` field of
+   `package.json`. It orders them so that each package comes after the packages it runs with
+   (`dependencies`, `peerDependencies` and `optionalDependencies`). `first` and `last` pin a package
+   to either end. Then it builds each manifest as it will publish:
+   - The version is the release's version.
+   - Each `workspace:` range on a package in the same train resolves to that version, the way pnpm
+     resolves `workspace:*`, `workspace:^` and `workspace:~`.
+   - Each `workspace:` range on a package in another train resolves to that train's last release,
+     which the plugin reads from the tags. `releasedVersions` from `@wtf/release-trains/packages`
+     and `resolveSpecifier` from `@wtf/release-npm/manifests` do this, and a train's cascade reads
+     the same functions.
+   - The plugin drops a devDependency whose `workspace:` range points at a package that no train
+     releases, such as a private package of shared configs, or at a train with no release yet. No
+     consumer installs a devDependency.
+   - The plugin strips each export that points at source: the `source` condition, or a `.ts`
+     target.
+
+   Then it checks each manifest. This step writes nothing.
+
+2. **Pack the tarballs** (`packTrain`). The plugin copies each package, without its `node_modules`,
+   into a folder in the system's temporary files. It writes the resolved manifest into the copy and
+   packs the copy there. It packs every package before the first publish, so a fault stops the run
+   before anything reaches the registry.
+
+3. **Publish** (`publishTrain`). The plugin publishes each package under the dist-tag of the
+   release's channel. That is `latest`, or `beta` for `2.1.0-beta.3`, or `prerelease` for
+   `2.1.0-0`. A channel that npm would read as a range, such as `1.x` on a maintenance branch,
+   becomes `release-1.x`. The plugin adds provenance where the CI provides an ID token, and skips
+   each version that the registry already has.
+
+### When a dist-tag would move back
+
+Before the first publish, the plugin asks the registry about every package (`publishedOf`). Suppose
+the registry does not have a package at the release's version, and the package's dist-tag points
+above the release. Publishing would move the dist-tag back, so the run fails with `EPUBLISHBEHIND`
+and publishes nothing. A prerelease on `latest` does not count as above a release: npm points
+`latest` at the first version of a package, even when that version is a prerelease.
+
+A package can join a train at a higher version of its own. Name such a package in `aside`. The
+plugin then publishes it under the dist-tag of its major's line, `release-<major>.x` in place of
+`latest`, and leaves its dist-tag where it is. If the line's dist-tag also points above the
+release, the run fails too. A release whose channel is a line already, such as `release-1.x` or
+`release-1.2.x` on a maintenance branch, puts nothing aside.
+
+### Which semantic-release step does what
+
+The plugin implements the same steps as `@semantic-release/npm`:
+
+- `verifyConditions` checks the publisher and the packages as they are in the repo.
+- `prepare` runs steps 1 and 2 and asks the registry, all before the tag. These faults fail the run
+  here:
+  - a range that no release satisfies (`EDEPENDENCYUNSATISFIED`);
+  - a dependency on a train with no release (`EDEPENDENCYNORELEASE`);
+  - a dependency on a package of no train (`EDEPENDENCYNOTRAIN`);
+  - a package that cannot be packed;
+  - a release that would move a dist-tag back (`EPUBLISHBEHIND`).
+- `publish` runs step 3 with what `prepare` packed, after the tag is pushed. It returns the release
+  to semantic-release as the stock plugin does: the publisher's name and its packages, the page of
+  the first package, and the channel. Then it removes the copies and the tarballs. With
+  `tarballDir`, it keeps the tarballs. If `publish` finds nothing packed for its train and version
+  in the same process, it resolves and packs again.
+- `addChannel` moves a published release to the dist-tag of its new channel, by `tagTrain`.
+  semantic-release asks for this when you merge a branch of one channel into the branch of another.
+  The plugin runs `npm dist-tag add` for each package of the train that the registry has at the
+  version, with either built-in publisher.
+
+npm moves a dist-tag only with the token in its config. Its trusted publishing covers
+`npm publish` and no other command, so a release from a channel branch needs `NPM_TOKEN` too. A
+publisher of your own moves dist-tags with its `tag` step; a publisher without one moves none.
+semantic-release records the new channel before it calls `addChannel`, so running again moves
+nothing. If moving a dist-tag fails, move it by hand, as the error says.
+
+## When packages depend on other trains
+
+A package can depend on a package in another train. The release then writes that train's last
+release into the range, as step 1 describes. Before the tag, the trains check that the other train
+has released, at a version that the range takes. They also decide the order of the trains, and when
+a train must release again because another train left its range behind. See
+[Trains that depend on other trains](dependency-rules.md).
+
+## Smoke-test the packages before the tag
+
+A workspace and its tests resolve each package from its source. They do not notice a file that the
+tarball misses, or an export that imports a peer the consumer has not installed. With `smoke`, the
+plugin tries each package it packed the way a consumer installs it, in `prepare`, before the tag. It
+tries the private packages of `pack` too. It does this with `smokePacked` from
+`@wtf/release-npm/smoke`, and it fails the run with `EPUBLISHSMOKE`, listing every fault it finds:
+
+- **In the tarball:** an entry of `files` that the tarball does not hold, as when a package was
+  packed without a build; an export with a source condition; a file that matches `forbid`, such as
+  `**/*.tsbuildinfo`.
+- **In the install:** npm installs the package in a project of its own in the system's temporary
+  files. Every other packed package installs from its tarball through npm's `overrides`, so npm does
+  not ask the registry for any of them.
+- **In the imports:** the plugin imports each entry of `exports`, except `./package.json` and
+  patterns. It reports a `SyntaxError`, a module not found that is neither an optional peer in the
+  manifest nor a bundler's own specifier, and an export that a packed package does not export. Any
+  other error from an import is the module's own and does not fail the smoke test. A package with no
+  `exports` and no `main`, such as a demo of static files, has nothing to import. The plugin only
+  installs it.
+
+The smoke test needs `tar`, `npm` and `node` where it runs. A job that runs no release, such as a
+merge request job, can run it for every train with the plugin's bin: see
+[Smoke-test packages in a merge request](ci-recipes.md#smoke-test-packages-in-a-merge-request).
+Some pipelines run the bin in a job before the publish job, as the
+[tag pipeline](ci-recipes.md#build-smoke-test-and-publish-in-a-tag-pipeline) for to-be-continuous
+does. Such a pipeline turns `smoke` off in the tag's run, with a variable that the publish job sets,
+so that the job holding the ID tokens only publishes.
+
+## What the check catches
+
+Before the first publish, the run fails with `EPUBLISHCHECK` when a package of the train:
+
+- is scoped and does not publish as public (`publishConfig.access`), which npm refuses;
+- names no `license`, or no `repository` with the `directory` of its folder;
+- runs with a private package of the workspace, which never publishes;
+- cannot be ordered, because of a pin that cannot hold or a cycle;
+- still has a `workspace:` range, an export with the `source` condition, or a `.ts` export after
+  the plugin resolved its manifest.
+
+## Registries and credentials
+
+The default `npm` publisher publishes to any registry that speaks npm's protocol. npm handles
+provenance and trusted publishing itself, with the CI's ID token. Without an ID token, npm uses the
+token in its config, such as `//registry.npmjs.org/:_authToken=${NPM_TOKEN}` in an `.npmrc`. To
+publish with another tool, choose another [publisher](#publishers). The recipes at the end show the
+GitLab package registry and JSR.
+
+## When a publish fails
+
+How you finish a failed publish depends on where the publish ran.
+
+### A publish in the tag's pipeline
+
+If `semantic-release-trains-tag` publishes in the tag's pipeline, retry the publish job and keep the
+tag. The retry packs the tagged commit's build again, skips each package the registry has, and
+publishes the rest. See
+[Build, smoke-test and publish in a tag pipeline](ci-recipes.md#build-smoke-test-and-publish-in-a-tag-pipeline).
+
+Do not delete the tag, and do not run the branch release again. When the branch config names no
+publish plugin, as in this setup, that run makes a second release commit with the same version. The
+stock `@semantic-release/changelog` writes the changelog again, and the run tags that commit. The
+first tag's pipeline never built that commit.
+
+### A publish in the release run
+
+If the plugin publishes in the release run itself, as in the config above, semantic-release pushes
+the release commit of `@semantic-release/git` and the tag before it runs `publish`. It does this for
+every plugin. A publish that fails part way leaves both behind, and a new run finds that version
+released and does nothing. To finish the release:
+
+1. Delete the tag on the remote and in the clone that runs again. A tag in the clone also counts as
+   a finished release.
+2. Run the release again at the release commit, the tip of the branch. semantic-release releases
+   nothing from a commit behind the tip.
+
+The run computes the same version, tags the release commit, skips each package the registry already
+has, publishes the rest, and creates the GitLab or GitHub release. A changelog plugin that the
+trains plugin wraps finds the release's section in the changelog and skips its `prepare`, so
+`@semantic-release/git` finds nothing to commit. If you list `@semantic-release/changelog`
+unwrapped, it writes the section again. Wrap it, or remove the second section before the run.
+
+A retried job that runs at its pipeline's commit, as a to-be-continuous job does, runs behind the
+release commit. Check out the tip first, where the tip is the pipeline's commit with only release
+commits on top. See [Run releases in CI](ci-recipes.md#gitlab-ci).
+
+## Use the steps as a library
+
+The three steps are functions of `@wtf/release-npm/release` and need no release tool. Each step runs
+on the `system` that its caller passes, as a CLI passes its own system adapted to the interface:
 
 ```ts
 import type { System } from '@wtf/release-system/system'
@@ -187,25 +281,14 @@ export async function release(system: System, version: string) {
 }
 ```
 
-`releaseTrain` runs the three in one call, as a job of the pipeline of a tag publishes its release:
-see [CI recipes](ci-recipes.md#publishing-from-the-tag).
-
-## The check
-
-Before the first publish, the run fails with `EPUBLISHCHECK` when a package of the train:
-
-- is scoped, and does not publish as public (`publishConfig.access`): npm refuses it;
-- names no `license`, or no `repository` with the `directory` of its folder;
-- runs with a package of the workspace that is private, which never publishes;
-- cannot be ordered: a pin that cannot hold, or a cycle;
-- still has a `workspace:` range, an export of the `source` condition, or a `.ts` export after its
-  manifest is resolved.
+`releaseTrain` runs all three in one call, the way a job in the tag's pipeline publishes its
+release. See [Publish from the tag pipeline](ci-recipes.md#publish-from-the-tag-pipeline).
 
 ## Publishers
 
-A publisher does two things: it looks a package up on the registry, and it publishes it. Its
-`lookup` answers, in one question, whether the registry has the version, and, where it reads
-dist-tags, the version the release's dist-tag points at, as `tagged`.
+A publisher does two things: it looks a package up on the registry, and it publishes the package.
+Its `lookup` answers two questions in one call: whether the registry has the version, and, if the
+publisher reads dist-tags, which version the release's dist-tag points at (`tagged`).
 
 ```ts
 import type { Publisher } from '@wtf/release-npm'
@@ -223,34 +306,38 @@ export const logOnly: Publisher = {
 }
 ```
 
-`pack` is optional. A publisher that packs has every package packed before the first publish, and
-gets its tarball as `options.tarball`. `page` is optional too: it gives the page of a package, which
-the plugin gives semantic-release as the URL of the release. `tag` is optional: it points a dist-tag
-at a version the registry has, for `addChannel` and `tagTrain`; without it, a release does not move
-to another channel. A `lookup` with no `tagged` is not checked for a dist-tag it would move back.
-
-The option `publisher` chooses one:
-
-- `npm`, the default, runs the `npm` bin: `npm view <name>@<tag> version versions dist-tags`
-  looks a package up, and of a dist-tag it has not, `@<version>`, once a step of the release, which
-  keeps the package's versions and dist-tags (the context's `memo`) and asks again of what it
-  changes;
-  `npm pack --ignore-scripts` packs, as the build ran before the release,
-  `npm publish <tarball>` publishes, and `npm dist-tag add` moves a dist-tag. npm itself handles
-  provenance, and the trusted publishing of its registry by the ID token of the CI. With no ID
-  token, npm uses the token of its config, such as `//registry.npmjs.org/:_authToken=${NPM_TOKEN}`
-  in an `.npmrc`.
-- `pnpm` runs `pnpm publish <copy> --no-git-checks --ignore-scripts` of the copy of each package,
-  from the root of the repo, or from the copy where the package has an `.npmrc` of its own, and
-  asks the registry and moves a dist-tag by npm.
-- The path of a module, such as `./release/publisher.mjs`, from the root of the repo, or the name of
-  a package. Its default export is the publisher.
-- A publisher itself, in a config written in JavaScript.
-
-### A recipe: yarn
-
-yarn publishes; npm, which reads the same registry, looks a package up, as the `npm` publisher
-does:
+A publisher can also have these optional members:
+
+- `pack`: with it, the plugin packs every package before the first publish and passes each tarball
+  as `options.tarball`.
+- `page`: it returns a package's page, which the plugin passes to semantic-release as the release's
+  URL.
+- `tag`: it points a dist-tag at a version the registry has, for `addChannel` and `tagTrain`.
+  Without it, a release cannot move to another channel.
+
+The plugin does not check whether a `lookup` without `tagged` would move a dist-tag back.
+
+The `publisher` option chooses the publisher:
+
+- **`npm`**, the default, runs the `npm` bin:
+  - `npm view <name>@<tag> version versions dist-tags` looks a package up. If the package has no
+    such dist-tag, the publisher asks for `@<version>` instead. It asks once per release step,
+    keeps the package's versions and dist-tags in the context's `memo`, and asks again only about
+    what it changes.
+  - `npm pack --ignore-scripts` packs, because the build ran before the release.
+  - `npm publish <tarball>` publishes.
+  - `npm dist-tag add` moves a dist-tag.
+- **`pnpm`** runs `pnpm publish <copy> --no-git-checks --ignore-scripts` on each package's copy. It
+  runs from the repo's root, or from the copy when the package has an `.npmrc` of its own. It uses
+  npm to ask the registry and to move dist-tags.
+- **The path of a module**, such as `./release/publisher.mjs` from the repo's root, or a package
+  name. Its default export is the publisher.
+- **A publisher object**, in a config written in JavaScript.
+
+### Recipe: publish with yarn
+
+yarn publishes, and npm looks each package up, as the `npm` publisher does. npm reads the same
+registry:
 
 ```js train=trains
 // release/yarn-publisher.mjs
@@ -277,10 +364,10 @@ export default {
 }
 ```
 
-### A recipe: the package registry of GitLab
+### Recipe: publish to the GitLab package registry
 
-The `npm` publisher publishes to any registry of npm's protocol. Name the registry of the project,
-and give npm the token of the job:
+The `npm` publisher works with this registry. Name the project's registry, and give npm the job's
+token:
 
 ```js train=trains
 // release.config.mjs
@@ -311,7 +398,7 @@ export default {
 echo "//${CI_SERVER_HOST}/api/v4/projects/${CI_PROJECT_ID}/packages/npm/:_authToken=\${CI_JOB_TOKEN}" >> .npmrc
 ```
 
-### A recipe: JSR
+### Recipe: publish to JSR
 
 ```js train=trains
 // release/jsr-publisher.mjs
@@ -332,5 +419,5 @@ export default {
 }
 ```
 
-JSR reads the version of the package from its `jsr.json`: write it into the copy, in `publish`,
-before `jsr publish`, as `pkg.version`.
+JSR reads the package's version from its `jsr.json`. In `publish`, write `pkg.version` into the
+copy's `jsr.json` before you run `jsr publish`.