@wtf/release-docs 8.2.0 → 8.2.2

package/guides/configuring-trains.md

@@ -1,9 +1,13 @@
-# Configuring trains
+# Configure trains
 
-## A train
+This page covers every option of a train, how the trains decide which commits count, and how to
+write the config that runs them. If you are new to trains, read
+[Getting started](getting-started.md) first.
 
-Each train is a key of the trains object. The key is the name of the train, and it is part of the
-tags of the train:
+## Declare a train
+
+Each key of the `trains` object declares a train. The key is the train's name, and it is part of
+the train's tags:
 
 ```ts
 import type { Trains } from '@wtf/release-trains'
@@ -42,73 +46,87 @@ export const trains: Trains = {
 }
 ```
 
-| Field       | Default                     | What it is                                                           |
-| ----------- | --------------------------- | -------------------------------------------------------------------- |
-| `paths`     | (required)                  | Folders or globs. A file is the train's when it is under one.        |
-| `shared`    | none                        | Files or folders outside the train that count for it too: see below. |
-| `tagFormat` | `<train>-v${version}`       | The tags of the train. It contains `${version}` exactly once.        |
-| `changelog` | `<first path>/CHANGELOG.md` | The changelog of the train, or `false`.                              |
-| `generated` | none                        | Folders that the build writes, committed by the release.             |
-| `dependsOn` | none                        | Trains this train releases after, besides those its packages list.   |
+| Field       | Default                     | What it does                                                                      |
+| ----------- | --------------------------- | --------------------------------------------------------------------------------- |
+| `paths`     | (required)                  | Folders or globs. A file belongs to the train when it is under one of them.       |
+| `shared`    | none                        | Files or folders outside the train that also count for it. See below.             |
+| `tagFormat` | `<train>-v${version}`       | The train's tags. It must contain `${version}` exactly once.                      |
+| `changelog` | `<first path>/CHANGELOG.md` | The train's changelog, or `false` for none.                                       |
+| `generated` | none                        | Folders that the build writes. The release commits them.                          |
+| `dependsOn` | none                        | Trains that this train releases after, besides the trains its packages depend on. |
 
-The types of a train are of `@wtf/release-trains`, the library, which has no dependency on
+The `Trains` type comes from the library `@wtf/release-trains`, which does not depend on
 semantic-release.
 
-### Dependencies between trains
+### Order trains by their dependencies
+
+A train depends on another train when one of its packages depends on a package in the other train.
+Every kind of dependency counts except a dev dependency:
+
+- In a `package.json`: `dependencies`, `peerDependencies` and `optionalDependencies`.
+- In a `Cargo.toml`: normal dependencies and build dependencies.
+
+A dev dependency does not order trains, because no user installs it.
+
+Let the manifests order the trains whenever a train installs a package of the other train. Name a
+train in `dependsOn` when your train must release after it but installs none of its packages. A
+docs train is an example: its reference shows the release of the trains it documents, but it lists
+their packages only in its `devDependencies`.
+
+A manifest dependency and a `dependsOn` entry count the same, both for the `dependencies` rule and
+for the order of the trains. Only a range in a manifest requires a version.
+
+A train also releases when a dependency train releases a version outside a range that the train's
+last release published. The root option `cascade` controls this, and it is `true` by default. See
+[Trains that depend on other trains](dependency-rules.md).
 
-A train depends on another train when one of its packages depends on a package of the other train,
-by any kind but `dev`: a `dependency`, a `peerDependency` or an `optionalDependency` of its
-`package.json`, or a normal or a build dependency of its `Cargo.toml`. A devDependency orders no
-train, as no user installs it. Use that whenever the train installs the other train's package. Name
-a train in `dependsOn` when the train must release after it, and installs none of its packages, as a
-docs train whose reference shows the release of the trains it documents and lists their packages of
-its devDependencies alone. Both count the same for the rule `dependencies` and for the order of the
-trains. Only a range of a manifest requires a version. A train also releases when a dependency train releases a version outside a range that its
-last release published, by the option `cascade` of the root, `true` by default. See
-[Dependency rules](dependency-rules.md).
+### Choose the files of a train
 
-### Paths and globs
+A folder holds every file under it. `packages/release-trains` holds
+`packages/release-trains/src/index.ts`, but not `packages/release-npm/src/index.ts`.
 
-A folder holds every file under it: `packages/release-trains` holds
-`packages/release-trains/src/index.ts`, and not `packages/release-npm/src/index.ts`. A
-glob holds each file that it matches, and every file under each folder that it matches:
-`packages/release-trains-*` holds `packages/release-npm/src/index.ts`. `.` holds every
-file of the repo.
+A glob holds each file that it matches, and every file under each folder that it matches.
+`packages/release-trains-*` holds `packages/release-trains-extra/src/index.ts`. `.` holds every
+file in the repo.
 
-A file belongs to one train only. The run fails with `ETRAINOVERLAP` when the paths of two trains
-hold the same file. A file that more than one train builds with, such as the lockfile, goes in the
-`shared` of each of those trains.
+A file belongs to one train only. When the paths of two trains hold the same file, the run fails
+with `ETRAINOVERLAP`. If several trains build with one file, such as the lockfile, put that file in
+the `shared` of each of those trains.
 
 ### Which commits count
 
-The trains plugin reads the files of each commit with `git diff-tree`. A file under the `paths` of a
-train is that train's own file. A commit counts for a train by its files:
+The trains plugin reads the files of each commit with `git diff-tree`. A file under a train's
+`paths` is one of that train's own files. A commit counts for a train by the files it changes:
 
-- A commit that changes the own files of one or more trains counts for each of those trains, and
-  for each train whose `shared` holds one of those files, as a docs train that shares the paths of
-  the trains it documents. The other files that it changes, as the lockfile or the root
-  `package.json`, count for no further train.
-- A commit that changes the own files of no train, as a commit of the lockfile alone, counts for
+- If the commit changes the own files of one or more trains, it counts for each of those trains. It
+  also counts for each train whose `shared` holds one of those files, such as a docs train that
+  shares the paths of the trains it documents. The other files it changes, such as the lockfile or
+  the root `package.json`, add no further train.
+- If the commit changes no train's own files, such as a commit of the lockfile alone, it counts for
   each train whose `shared` holds one of its files.
 
 A commit that changes the files of two trains counts for both, and appears in the notes of both. A
-merge commit counts for the files that it brings into its branch, which are its changes against its
+merge commit counts for the files it brings into its branch, which are its changes against its
 first parent.
 
-So a breaking change in train `trains` makes a major release of `trains` only. A `feat` of train
-`replace` that adds a dependency, and so changes the lockfile too, releases `replace`, and not each
-train that lists the lockfile in its `shared`. A `fix` of the lockfile alone releases each train
-that lists the lockfile in its `shared`, and no other train.
+Some examples:
+
+- A breaking change in train `trains` makes a major release of `trains` only.
+- A `feat` in train `replace` that adds a dependency also changes the lockfile. It releases
+  `replace`, but not each train that lists the lockfile in its `shared`.
+- A `fix` of the lockfile alone releases each train that lists the lockfile in its `shared`, and no
+  other train.
 
 ### Generated folders
 
-A folder in `generated`, such as an API reference that a build writes, is committed with the
-release, and a page that the build no longer writes leaves git. The build lists what it wrote, in
-the folder's `.generated`, and an entry of `@wtf/semantic-release-trains` of `generated: true`
-stages the folder from that list in `prepare`: every file of it unstaged, each one the list names staged, though git
-ignores the folder, and each other removed. This matters when the release job gets the build of
-another job, because unpacking that build over the checkout leaves the pages of the last release.
-At the end of the build, after it wrote the folder in full:
+Use `generated` when a build writes a folder that the release must commit, such as an API
+reference. The release commits the folder, and a page that the build no longer writes leaves git.
+
+This matters when the release job gets its build from another job. Unpacking that build over the
+checkout adds the new pages, but it also leaves the pages of the last release in place.
+
+So the build lists what it wrote, in the folder's `.generated` file. Call `listGenerated` at the end
+of the build, after the build has written the folder in full:
 
 ```ts
 import { nodeSystem } from '@wtf/release-system/node'
@@ -118,8 +136,15 @@ const system = nodeSystem()
 await listGenerated(system.cwd, 'packages/docs/api', { system })
 ```
 
-With no list, the entry stages the folder as it is, deletions too. Its folders are the `generated`
-of the train of the run:
+In `prepare`, an entry of `@wtf/semantic-release-trains` with `generated: true` stages the folder
+from that list:
+
+1. It unstages every file in the folder.
+2. It stages each file that the list names, even when git ignores the folder.
+3. It removes every other file.
+
+Without a list, the entry stages the folder as it is, deletions included. The entry stages the
+`generated` folders of the run's train:
 
 ```js train=docs
 // release.config.mjs
@@ -137,36 +162,52 @@ export default {
 }
 ```
 
-List it after the build that writes the folders, and before `@semantic-release/git`, which then
-commits what it staged. An entry has one role: `generated` beside `wrap` fails with `EOPTIONS`.
+List the entry after the build that writes the folders, and before `@semantic-release/git`, which
+then commits what the entry staged. Each entry has one role: `generated` together with `wrap` fails
+with `EOPTIONS`.
 
 ### Replacements
 
-A version written into a file of the repo, as the badge of shields.io of a README, is wrong from the
-next release, and nothing fails then. The plugin `@wtf/semantic-release-replace` replaces text in
-files in `prepare`, of no train: each match of each of its `replacements`, in each file of its
-`files`. Its options, each JSON:
-
-| Option         | What it is                                                                                            |
-| -------------- | ----------------------------------------------------------------------------------------------------- |
-| `files`        | Paths, globs and negations, in order, from the root, of the files git tracks: required                |
-| `replacements` | Each `{ from, flags, to, escape }`, or of a template, `{ template, … }` or its name alone: required   |
-| `templates`    | Replacements by name: a set, or sets merged in order; at the root of the config too, under an entry's |
-
-`files` holds, of a path, the file, or each file under the folder; of a glob, each file it matches,
-`*` and `?` within a name, `**` across folders, `[…]` a class, `[^…]` one not of it, and `{a,b}`
-each of a list; an entry of `!` first leaves out what it matches of what the entries before it hold.
-A replacement replaces each match of `from`, the source of a RegExp, of its `flags` but `g`, by
-`to`: a text of `$1` each group of the match and `${nextRelease.version}` each value of the context
-of the release by its dotted path, as the message of `@semantic-release/git` writes one, each value
-as `escape` writes it, `none`, the default, `shields`, each `-` and `_` doubled, as the text of a
-badge of shields.io takes them, or `url`; or the function of a module, `{ module, export }`.
-
-A template is a replacement of a name, defined once in `templates`, at the root of the config,
-which semantic-release gives every plugin, or of an entry, whose own are over the root's of the same
-name. A replacement names it, alone, as `"badge"`, or with options over the template's own, as
-`{ "template": "badge", "escape": "none" }`; a name of no template fails the run before it releases,
-with `ETEMPLATE`, naming those there are. The badge of the version, as a config defines it:
+Use `@wtf/semantic-release-replace` to keep a version that is written in a file up to date, such as
+the version in a shields.io badge of a README. Without it, that version is wrong from the next
+release on, and nothing fails.
+
+The plugin replaces text in files in `prepare`. It does not depend on the train. It replaces each
+match of each of its `replacements` in each file of its `files`. All of its options are JSON:
+
+| Option         | What it does                                                                                                         |
+| -------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `files`        | Required. Paths, globs and negations, applied in order, from the root, to the files that git tracks.                 |
+| `replacements` | Required. Each one is `{ from, flags, to, escape }`, or a template: `{ template, … }`, or the template's name alone. |
+| `templates`    | Replacements by name: one set, or several sets merged in order. Also allowed at the root of the config.              |
+
+Each entry of `files` selects files:
+
+- A path selects the file, or each file under the folder.
+- A glob selects each file it matches. `*` and `?` match within a name, `**` matches across
+  folders, `[…]` matches one character of a class, `[^…]` one character outside it, and `{a,b}`
+  each item of a list.
+- An entry that starts with `!` leaves out what it matches from what the entries before it
+  selected.
+
+A replacement replaces each match of `from` by `to`:
+
+- `from` is the source of a RegExp. `flags` holds its flags; the plugin always adds `g`, so leave
+  `g` out.
+- In `to`, `$1` stands for a group of the match. `${nextRelease.version}` stands for a value of the
+  release context, by its dotted path, in the same syntax as the message of `@semantic-release/git`.
+- `escape` sets how each context value is written: `none` (the default) as it is, `shields` with
+  each `-` and `_` doubled as a shields.io badge needs them, or `url`.
+- `to` can also name the function of a module instead of a text: `{ module, export }`.
+
+A template is a replacement with a name. You define it once in `templates`, either at the root of
+the config, which semantic-release gives every plugin, or in an entry. An entry's own templates
+override the root's templates of the same name.
+
+A replacement names a template alone, as `"badge"`, or with options that override the template's
+own, as `{ "template": "badge", "escape": "none" }`. A name that no template has fails the run with
+`ETEMPLATE` before it releases, and the error lists the templates that exist. This config defines
+the version badge:
 
 ```json
 {
@@ -193,12 +234,17 @@ with `ETEMPLATE`, naming those there are. The badge of the version, as a config
 }
 ```
 
-A package shares templates, as the badge of the version, which each repo would else write again.
-`templates` is a set, or an array of sets merged in order, each over those before it by name. A set
-is a map of each template by its name, a replacement or the export of a module that is one; or the
-export of a module that is a set, each of whose templates comes in under its own name. A module is
-named as a function is, `{ module, export }`, `default` by default, as of a package of templates this
-repo does not have, `@wtf/replace-shields`:
+A package can share templates, such as the version badge, so that each repo does not write them
+again. `templates` is one set, or an array of sets merged in order. Each set overrides the sets
+before it by name. A set can be:
+
+- A map of templates by name. Each template is a replacement, or the export of a module that is
+  one.
+- The export of a module that is a set. Each of its templates keeps its own name.
+
+You name a module the same way as a function: `{ module, export }`, where `export` is `default` by
+default. This example uses `@wtf/replace-shields`, a package of templates that this repo does not
+have:
 
 ```json
 {
@@ -216,28 +262,37 @@ repo does not have, `@wtf/replace-shields`:
 }
 ```
 
-The plugin imports each in `verifyConditions`: `EREPLACEMODULE` of a module it cannot load, or of
-no such export; `ETEMPLATE` of an export of no replacement, or of no set. It takes a package of the
-repo's, a devDependency; else one installed beside it, of a global install of semantic-release, as
-the semantic-release component of to-be-continuous makes one: list the package in its
-`semrel-required-plugins.txt` (see [CI recipes](ci-recipes.md)).
-
-List it before `@semantic-release/git`, whose `assets` hold the files it replaces:
-`trainAssets(trains, train, { replaced: 'README.md' })` lists the README.md of each folder of the
-train, as `` `packages/*-${train}/README.md` `` does in [a config of literals](#a-config-of-literals)
-of these trains. The release commit then
-commits each, and the packages are packed of it, of their READMEs replaced. See
+The plugin imports each module in `verifyConditions`. It fails with:
+
+- `EREPLACEMODULE` when it cannot load a module, or the module has no such export.
+- `ETEMPLATE` when an export is not a replacement, or not a set.
+
+It loads a package that the repo installs, as a devDependency. Otherwise it loads one that is
+installed beside the plugin, as in a global install of semantic-release. The semantic-release
+component of to-be-continuous makes such an install: list the package in its
+`semrel-required-plugins.txt` (see [Run releases in CI](ci-recipes.md)).
+
+List the plugin before `@semantic-release/git`, and put the files it replaces in the git plugin's
+`assets`. `trainAssets(trains, train, { replaced: 'README.md' })` lists the README.md of each
+folder of the train. In [a config of literals](#a-config-of-literals) of these trains,
+`` `packages/*-${train}/README.md` `` does the same. The release commit then commits each README,
+and the packages are packed with their replaced READMEs. See
 [`@wtf/semantic-release-replace`](../../semantic-release-replace/README.md).
 
-## The config
+## Write the config
 
-`release.config.mjs` is yours: the plugins, their options and their order. The plugins of the trains
-read `trains` and `ecosystems` of the root, which semantic-release gives every plugin, and the train
-of the run of `RELEASE_TRAIN` of its environment, as a plugin of semantic-release reads a variable
-of its own. `ecosystems` is required: the name of the module of each ecosystem of the repo, whose
-packages the trains read, as `@wtf/release-npm` of each `package.json`. Each is loaded of the repo,
-as an entry of `wrap` loads the plugin it wraps, by its name, its path from the repo, or its `file:`
-URL; one that cannot be loaded, or whose default export is no ecosystem, fails with `EECOSYSTEM`:
+`release.config.mjs` is yours: you choose the plugins, their options and their order. The trains
+plugins read these values:
+
+- `trains` and `ecosystems` from the root of the config, which semantic-release gives every plugin.
+- The run's train from `RELEASE_TRAIN` in the run's environment, the same way any semantic-release
+  plugin reads a variable of its own.
+
+`ecosystems` is required. It names the module of each ecosystem in the repo, and the trains read
+the packages through it. For example, `@wtf/release-npm` reads each `package.json`. Each module is
+loaded from the repo, the same way a `wrap` entry loads the plugin it wraps: by its name, its path
+from the repo, or its `file:` URL. A module that cannot be loaded, or whose default export is not
+an ecosystem, fails with `EECOSYSTEM`:
 
 ```js train=trains
 // release.config.mjs
@@ -298,58 +353,70 @@ export default {
 }
 ```
 
-The values of `@wtf/semantic-release-trains/config`:
-
-| Value                                 | What it is                                                                                                                           |
-| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
-| `trainTagFormat(trains, train)`       | The tag format of the train, for `tagFormat`. The trains plugin fails with `ETAGFORMAT` of another.                                  |
-| `trainChangelog(trains, train)`       | The changelog of the train, for `trainChangelog` of the changelog plugin, or `changelogFile` of `@semantic-release/changelog`.       |
-| `trainAssets(trains, train, options)` | The `assets` of `@semantic-release/git`: the changelogs, the files replaced (`replaced`), and the generated folders.                 |
-| `trainOfTag(trains, tag)`             | The train whose tag format names a tag, as of `RELEASE_TAG` of the run of a tag: see [CI recipes](ci-recipes.md).                    |
-| `skipPlugins(plugins, pattern, opts)` | The entries of `plugins` but those a pattern of their step ids matches, as a job leaves out a step: see [CI recipes](ci-recipes.md). |
-| `BRANCHES`                            | `main`, and `rc`, `pre`, `beta` and `alpha` as prereleases.                                                                          |
-| `BREAKING`                            | The parser options that read `type!:` as a breaking change, for the root.                                                            |
-
-These values are for a config that imports them, of a repo that installs the plugins. A config that
-a global install of semantic-release reads, as the semantic-release component of to-be-continuous
-reads one, imports nothing of them: see [A config of literals](#a-config-of-literals).
-
-The order of `plugins` is the order of each step. Of `prepare`: the changelogs, then the files
-replaced, then the packages packed, then the generated folders staged, then the release commit.
-After the tag, of `publish`: the packages, then the release of the host, last.
-
-The plugin of the trains is one package, listed once for each role, each entry where its role runs:
-of `wrap`, where the plugin it wraps runs; of `generated`, after the build that writes the folders;
-and every entry checks the trains, once a run. It needs all the trains, not only the train of the
-run, to find overlapping paths and dependencies. With one train, a config needs no entry of `wrap`:
-the stock analyzer and notes generator read every commit.
-
-### The train of a run
-
-Each plugin of the trains reads the train of the run of its option `train`, or else of
-`RELEASE_TRAIN` of the environment of the run, never of the process's own: the option wins. Of
-neither, the run fails with `ETRAINNOTSELECTED`. The environment is the simpler way, as above: the
-config declares the trains, and each job names its train. A config that names it at its root, as
-`train: process.env.RELEASE_TRAIN`, does the same.
-
-The tag format is semantic-release's own, `tagFormat` of the config or `--tag-format` of the
-command, and must be the train's, or the run would read the tags of another train: the trains plugin
-fails with `ETAGFORMAT` of another.
-
-### On the train
-
-semantic-release gives each plugin its own copy of the context of a run, with every commit of the
-repo since the train's last tag, so no plugin can filter the commits of another. It releases by the
-highest type of release that any analyzer returns, and joins the notes of every generator; the
-plugin of the host comments on the merge request of each commit when the release succeeds. So wrap
-each plugin that reads the commits in an entry of `@wtf/semantic-release-trains` of `wrap`, which
-gives each of its steps the commits of the train alone: the commit analyzer, the release notes
-generator, the plugin of the host, and any other. List no commit analyzer and no release notes
-generator unwrapped: it would bump the train by the commits of every other train, or add their
-notes.
-
-`wrap` names the plugin as an entry of `plugins` names one. The array form, the plugin's name and
-its options, is where the options of that plugin go, as its `preset` or `releaseRules`:
+`@wtf/semantic-release-trains/config` exports these values:
+
+| Value                                 | What it gives                                                                                                                                       |
+| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `trainTagFormat(trains, train)`       | The train's tag format, for `tagFormat`. The trains plugin fails with `ETAGFORMAT` when `tagFormat` is any other.                                   |
+| `trainChangelog(trains, train)`       | The train's changelog, for `changelogFile` of `@semantic-release/changelog`, or `undefined` for a train with no changelog.                          |
+| `trainAssets(trains, train, options)` | The `assets` of `@semantic-release/git`: the changelogs, the replaced files (`replaced`), and the generated folders.                                |
+| `trainOfTag(trains, tag)`             | The train whose tag format matches a tag, such as `RELEASE_TAG` in a run on a tag. See [Run releases in CI](ci-recipes.md).                         |
+| `skipPlugins(plugins, pattern, opts)` | The entries of `plugins` without those whose step ids match a pattern, so that a job can leave out a step. See [Run releases in CI](ci-recipes.md). |
+| `BRANCHES`                            | `main`, and `rc`, `pre`, `beta` and `alpha` as prereleases.                                                                                         |
+| `BREAKING`                            | The parser options that read `type!:` as a breaking change. Spread them at the root.                                                                |
+
+These values are for a config that imports them, in a repo that installs the plugins. A config
+that a global install of semantic-release reads, such as the one the semantic-release component of
+to-be-continuous reads, imports nothing from them. See [A config of literals](#a-config-of-literals).
+
+The order of `plugins` is the order within each step:
+
+- In `prepare`: the changelogs, then the replaced files, then the packed packages, then the staged
+  generated folders, then the release commit.
+- In `publish`, after the tag: the packages, then the release on the host, last.
+
+The trains plugin is one package that you list once for each role. Put each entry where its role
+runs:
+
+- A `wrap` entry goes where the plugin it wraps would run.
+- A `generated` entry goes after the build that writes the folders.
+- Every entry checks the trains, once a run.
+
+The plugin needs all the trains, not only the run's train, so that it can find overlapping paths
+and dependencies. With one train, a config needs no `wrap` entry: the stock analyzer and notes
+generator read every commit.
+
+### Choose the train of a run
+
+Each trains plugin reads the run's train from its option `train`. Without that option, it reads
+`RELEASE_TRAIN` from the run's environment, never from its own process. The option wins over the
+variable. With neither, the run fails with `ETRAINNOTSELECTED`.
+
+The environment is the simpler way, as above: the config declares the trains, and each job names
+its train. A config that sets `train: process.env.RELEASE_TRAIN` at its root does the same.
+
+The tag format is semantic-release's own: `tagFormat` in the config, or `--tag-format` on the
+command line. It must be the train's tag format, or the run would read the tags of another train.
+The trains plugin fails with `ETAGFORMAT` when it is any other.
+
+### Give each plugin only the train's commits
+
+semantic-release gives each plugin its own copy of the run's context. That context holds every
+commit in the repo since the train's last tag, so no plugin can filter the commits for another
+plugin. semantic-release then:
+
+- releases by the highest release type that any analyzer returns,
+- joins the notes of every notes generator,
+- lets the host plugin comment on the merge request of each commit when the release succeeds.
+
+So wrap each plugin that reads the commits in a `wrap` entry of `@wtf/semantic-release-trains`. The
+entry gives each step of the wrapped plugin only the train's commits. Wrap the commit analyzer, the
+release notes generator, the host plugin, and any other plugin that reads commits. Do not list a
+commit analyzer or a release notes generator unwrapped. It would bump the train for the commits of
+every other train, or add their notes.
+
+`wrap` names a plugin the same way an entry of `plugins` does. Use the array form, the plugin's
+name and its options, to give that plugin options such as its `preset` or `releaseRules`:
 
 ```js fragment
 ;[
@@ -363,47 +430,65 @@ its options, is where the options of that plugin go, as its `preset` or `release
 ]
 ```
 
-The name alone is the shorthand of a plugin with no options of its own:
+Use the name alone for a plugin with no options of its own:
 
 ```js fragment
 ;['@wtf/semantic-release-trains', { wrap: '@semantic-release/release-notes-generator' }]
 ```
 
-The wrapped plugin is given the options of the root of the config, with its own over them, as
-semantic-release gives any plugin its options over the root's. Any preset works, as does any plugin.
-The entry loads it as semantic-release loads a plugin: of the plugins semantic-release depends on
-itself, as the commit analyzer and the release notes generator, in the node_modules of the
-semantic-release beside it, of a global install too; or else of the repo, which installs any other;
-or else beside the plugin of the trains, as of a global install of semantic-release and its
-plugins. Of a global install, as the semantic-release component of to-be-continuous makes one of
-each name of `plugins`, a wrapped plugin that is no dependency of semantic-release, as
-`@semantic-release/gitlab`, is a name of its own to install beside it: list it in the component's
-`semrel-required-plugins.txt`. A shared config (`extends`) that wraps a plugin the repo does not
-install names it by its path, or by the URL `import.meta.resolve('@semantic-release/gitlab')` of the
-config gives: semantic-release finds the plugins of a shared config of its folder, which it gives no
-plugin. A `wrap` of another shape, or of the plugin of the trains itself, fails with `EOPTIONS`; a
-plugin it cannot load, with `EPLUGINLOAD`. The analyzer it wraps also checks the trains the train
-depends on, by `dependencies` of the root, and releases the train of what they released, by
-`cascade` of the root, which the notes generator it wraps says: see
-[Dependency rules](dependency-rules.md).
-
-semantic-release calls each step of the plugin of every entry. Of a step an entry has no role in,
-or the plugin it wraps has not, the entry gives what semantic-release takes as nothing: no type of
-release, and no notes (`''`, which semantic-release leaves out of the notes it joins). Of the steps
-of a release, `publish` and `addChannel`, it gives `false`, which semantic-release lists as a
-release of no name, of the plugin of the trains: the plugins of the host, which say the releases of
-a run by their names, leave it out, and the releases of a name are those of the plugins that
-published.
+The wrapped plugin gets the root options of the config, with its own options over them, the same
+way semantic-release gives any plugin its options. Any preset works, and so does any plugin.
+
+The entry loads the wrapped plugin the same way semantic-release loads a plugin. It looks in these
+places, in order:
+
+1. For a plugin that semantic-release itself depends on, such as the commit analyzer and the
+   release notes generator: the node_modules of the semantic-release beside it, also in a global
+   install.
+2. The repo, which installs any other plugin.
+3. Beside the trains plugin, as in a global install of semantic-release and its plugins.
+
+In a global install, such as the one the semantic-release component of to-be-continuous makes from
+each name in `plugins`, a wrapped plugin that semantic-release does not depend on needs an install
+of its own. `@semantic-release/gitlab` is an example: list it in the component's
+`semrel-required-plugins.txt`.
+
+A shared config (`extends`) that wraps a plugin the repo does not install must name that plugin by
+its path. Or it can use the URL that `import.meta.resolve('@semantic-release/gitlab')` gives in the
+shared config. semantic-release finds the plugins of a shared config in that config's folder, but
+it does not give that folder to any plugin.
+
+The entry fails with:
+
+- `EOPTIONS` when `wrap` has any other shape, or wraps the trains plugin itself.
+- `EPLUGINLOAD` when it cannot load the plugin.
+
+The analyzer that an entry wraps also checks the trains that the train depends on, by the root
+option `dependencies`. It also releases the train when they released outside a published range, by
+the root option `cascade`, and the wrapped notes generator lists those releases. See
+[Trains that depend on other trains](dependency-rules.md).
+
+semantic-release calls every step of the plugin of every entry. Sometimes an entry has no role in a
+step, or the plugin it wraps has no such step. Then the entry returns what semantic-release takes
+as nothing: no release type, and empty notes (`''`, which semantic-release leaves out of the notes
+it joins). For the release steps, `publish` and `addChannel`, it returns `false`. semantic-release
+lists that as a release with no name from the trains plugin. The host plugins announce the releases
+of a run by name, so they leave it out. The named releases are those of the plugins that published.
 
 ### A config of literals
 
-Each entry of the plugin of the trains is JSON, which a config writes as it is. A config of
-literals imports nothing, and awaits nothing: as one a global install of semantic-release reads, before anything of the repo is
-installed. The semantic-release component of to-be-continuous makes `.releaserc.json` of a
-`release.config.mjs` by `require()`, which takes no top-level `await`, before it installs the
-plugins, and installs each name of `plugins` then, by `npm install --global`: so each plugin is a
-package of its own, named whole, and each option of each is JSON. The values of
-`@wtf/semantic-release-trains/config` are written out: the tag format of the train as
+Each entry of the trains plugin is JSON, so a config can write it as it is. A config of literals
+imports nothing and awaits nothing. A global install of semantic-release can read it before
+anything in the repo is installed.
+
+The semantic-release component of to-be-continuous works this way:
+
+1. It makes `.releaserc.json` from `release.config.mjs` with `require()`, which does not allow a
+   top-level `await`. It does this before it installs any plugin.
+2. Then it installs each name in `plugins` with `npm install --global`.
+
+So each plugin must be a package of its own, named in full, and each option of each plugin must be
+JSON. Write out the values of `@wtf/semantic-release-trains/config`: the train's tag format as
 `${train}-v\${version}`, and `BREAKING` as `parserOpts`.
 
 ```js train=replace
@@ -448,8 +533,8 @@ export default {
 }
 ```
 
-A JSON config, as `.releaserc.json`, writes the same, of no train, which each job gives in its
-environment, and the job gives the train's tag format on the command line:
+A JSON config, such as `.releaserc.json`, writes the same without a train. Each job gives the train
+in its environment, and passes the train's tag format on the command line:
 
 ```json
 {
@@ -482,10 +567,10 @@ RELEASE_TRAIN=trains npx semantic-release --tag-format 'trains-v${version}'
 
 ### A preset, and `type!:`
 
-The default preset of semantic-release, `angular`, does not read a `!` after the type, as in
-`feat!: drop Node 20`. Spread `BREAKING` of `@wtf/semantic-release-trains/config` at the root of the
-config: it is a `breakingHeaderPattern` of the parser at the
-root of the config, so that every plugin reads `type!:` as a breaking change.
+semantic-release's default preset, `angular`, does not read a `!` after the type, as in
+`feat!: drop Node 20`. Spread `BREAKING` from `@wtf/semantic-release-trains/config` at the root of
+the config. It sets the parser's `breakingHeaderPattern` at the root, so that every plugin reads
+`type!:` as a breaking change.
 
 > **Caveat.** Do not trust `type!:` alone. A tool that reads the commits with other parser options
 > (another analyzer, a CI job that keeps only some options, or a preset that ignores the pattern)
@@ -498,13 +583,16 @@ root of the config, so that every plugin reads `type!:` as a breaking change.
 > BREAKING CHANGE: a train with no commits of its own releases too; set cascade: false for none.
 > ```
 
-## The libraries
+## Use the libraries directly
+
+`@wtf/release-trains` holds what the trains plugin runs, and it does not depend on semantic-release.
+Each function takes the `system` it runs on, so a CLI can pass its own. The parts that know nothing
+about trains (the system, paths and globs, git, validators and `ReleaseError`) live in
+`@wtf/release-system`, which `@wtf/release-trains` builds on.
 
-`@wtf/release-trains` holds what the trains plugin runs, with no dependency on semantic-release.
-Each function takes the `system` it runs by, as a CLI passes its own. What is of no train, the
-system, paths and globs, git, validators and `ReleaseError`, is of `@wtf/release-system`, which it
-builds on. It reads no manifest: the packages of the repo are those its ecosystems give, as the
-default export of `@wtf/release-npm` gives those of each `package.json`:
+`@wtf/release-trains` reads no manifest itself. The repo's packages are the ones its ecosystems
+give. For example, the default export of `@wtf/release-npm` gives the packages of each
+`package.json`:
 
 ```ts
 import npm from '@wtf/release-npm'