@wtf/release-docs 8.2.0 → 8.2.2

package/guides/system.md

@@ -1,11 +1,20 @@
 # The system
 
-Every function of the libraries, `@wtf/release-trains`, `@wtf/release-npm` and
-`@wtf/release-replace`, does its work outside itself through a
-`System` of `@wtf/release-system`, the base they build on, which it requires and never makes of its
-own: files, processes, the environment, the working folder, a folder of
-temporary files, and the clock. None of their modules names Node. A plugin of semantic-release
-passes Node's system; a CLI passes its own, adapted to the interface; a test passes one in memory.
+Read this page when you want to run the libraries outside semantic-release, from a CLI of your own,
+or in tests. You can also use it to change how the plugins run processes.
+
+Every function of the libraries, such as `@wtf/release-trains`, `@wtf/release-npm` and
+`@wtf/release-replace`, reaches the outside world through a `System`. The `System` type comes from
+`@wtf/release-system`, the base that the other libraries build on. A function requires a system
+from its caller and never makes one itself.
+
+The system provides files, processes, the environment, the working folder, a folder for temporary
+files, and the clock. None of the library modules names Node. Each caller passes the system that
+fits it:
+
+- A semantic-release plugin passes Node's system.
+- A CLI adapts its own files and processes to the interface, and passes that.
+- A test passes a system in memory.
 
 ```ts
 import type { System } from '@wtf/release-system/system'
@@ -14,24 +23,27 @@ import type { System } from '@wtf/release-system/system'
 export type Members = keyof System // 'fs' | 'exec' | 'env' | 'cwd' | 'tmpdir' | 'now'
 ```
 
-| Member   | What it is                                                                                                                  |
-| -------- | --------------------------------------------------------------------------------------------------------------------------- |
-| `fs`     | `readFile`, `writeFile`, `readdir`, `exists`, `mkdir` and `rm` of text, and `copy` byte for byte, of absolute paths         |
-| `exec`   | `exec(command, args, { cwd, env, input })`, which gives `{ stdout, stderr, code }`: the system's `cwd` and `env` by default |
-| `env`    | The environment that a process gets                                                                                         |
-| `cwd`    | The working folder                                                                                                          |
-| `tmpdir` | A folder of temporary files, outside the repo, where the packages of a release are copied and packed                        |
-| `now`    | The time, which dates a changelog                                                                                           |
+| Member   | What it is                                                                                                                             |
+| -------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `fs`     | `readFile`, `writeFile`, `readdir`, `exists`, `mkdir` and `rm` for text, and `copy` byte for byte. Every path is absolute.             |
+| `exec`   | `exec(command, args, { cwd, env, input })`, which returns `{ stdout, stderr, code }`. It uses the system's `cwd` and `env` by default. |
+| `env`    | The environment that a process gets.                                                                                                   |
+| `cwd`    | The working folder.                                                                                                                    |
+| `tmpdir` | A folder for temporary files, outside the repo. A release copies and packs its packages there.                                         |
+| `now`    | The current time, which dates a changelog.                                                                                             |
 
-A non-zero exit code is not a failure of `exec` itself: the caller decides. `exec` rejects only when
-the command cannot start. Paths are POSIX paths, which `@wtf/release-system/posix` joins, of no
-system.
+A non-zero exit code is not a failure of `exec` itself, and the caller decides what it means.
+`exec` rejects only when the command cannot start.
 
-## Node's system
+Paths are POSIX paths. `@wtf/release-system/posix` joins them, without needing a system.
 
-`nodeSystem` of `@wtf/release-system/node` is Node's: `node:fs/promises`, `node:child_process`,
-`process.env`, `process.cwd()`, `os.tmpdir()` and `new Date()`. It is the one module of the
-libraries that names Node, and only a caller on Node imports it: a plugin, a build script, a test.
+## Use Node's system
+
+`nodeSystem` from `@wtf/release-system/node` is Node's system. It uses `node:fs/promises`,
+`node:child_process`, `process.env`, `process.cwd()`, `os.tmpdir()` and `new Date()`.
+
+It is the only library module that names Node. Only a caller that runs on Node imports it, such as
+a plugin, a build script or a test.
 
 ```ts
 import { nodeSystem } from '@wtf/release-system/node'
@@ -41,10 +53,10 @@ const system = nodeSystem()
 export const packages = await readWorkspace(system.cwd, { system })
 ```
 
-## A system of your own
+## Write a system of your own
 
 A CLI with its own files and processes adapts them to the interface, and passes the result to each
-function:
+function. This example logs each process before it runs:
 
 ```ts
 import npm from '@wtf/release-npm'
@@ -72,13 +84,17 @@ export function check(system: System) {
 }
 ```
 
-## The plugins
+## Change the system that the plugins use
+
+Each plugin makes Node's system for the run. It builds the system from the folder and the
+environment that semantic-release gives each step, `cwd` and `env`, which the plugin requires. It
+passes that system to every call into its library, so each process runs in that folder and with
+that environment.
 
-Each plugin makes Node's system of the run, of the folder and the environment semantic-release
-gives each step, `cwd` and `env`, which it requires, and passes it to every call of its library: a
-process of it runs there, and of that environment. Its option `system`, or one at the root of the
-config, replaces members of it, merged by `systemOf` of `@wtf/release-system/node`, its `fs` member
-by member:
+To replace members of that system, set the plugin's `system` option, or a `system` option at the
+root of the config. `systemOf` from `@wtf/release-system/node` merges it over Node's system. It
+merges `fs` member by member. This example stops every process of the release from asking for a
+password:
 
 ```js train=trains
 // release.config.mjs
@@ -110,13 +126,13 @@ export default {
 }
 ```
 
-semantic-release copies the config for each plugin. It keeps the functions of an object, so a
-system in a `release.config.mjs` reaches each plugin. A config written in JSON has no system: the
-plugins then run on Node's system.
+semantic-release copies the config for each plugin. The copy keeps the functions of an object, so
+a system in a `release.config.mjs` reaches each plugin. A config written in JSON cannot hold a
+system, so the plugins then run on Node's system.
 
-## In tests
+## Use a system in tests
 
-A system of files in memory and of scripted processes runs the libraries with no disk and no git:
+A system with files in memory and scripted processes runs the libraries with no disk and no git:
 
 ```ts
 import type { System } from '@wtf/release-system/system'

package/guides/troubleshooting.md

@@ -1,52 +1,363 @@
 # Troubleshooting
 
-## The errors
-
-Each error of these packages is a `ReleaseError` of `@wtf/release-system/errors`, of the class of
-its package, `TrainsError` of `@wtf/release-trains/errors` or `ReplaceError` of
-`@wtf/release-replace/errors`, which semantic-release prints as it prints its own errors: the code,
-the message, and the details, which say how to fix it. A step that finds more than one fault
-reports all of them. git fails with `EGIT`, a `ReleaseError` itself; a validator of options of
-`@wtf/release-system` with `EOPTIONS`, or the code its check gives, of the class of the package
-that asks.
-
-| Code                     | Package                   | What is wrong                                                                                                                           | The fix                                                                                                                                                                                              |
-| ------------------------ | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `ETRAINNOTSELECTED`      | `release-trains`          | No train is chosen for the run.                                                                                                         | Set `RELEASE_TRAIN` of the job, or `train` of the root of the config.                                                                                                                                |
-| `ETRAINUNKNOWN`          | `release-trains`          | The chosen train is not declared.                                                                                                       | Choose a declared train, or declare it.                                                                                                                                                              |
-| `ETRAINNAME`             | `release-trains`          | The name of a train cannot be part of a tag.                                                                                            | Use letters, digits, `.`, `_` and `-`.                                                                                                                                                               |
-| `ETRAINPATHS`            | `release-trains`          | A train declares no paths.                                                                                                              | Give it `paths`.                                                                                                                                                                                     |
-| `ETRAINOVERLAP`          | `release-trains`          | The paths of two trains hold the same file, or the folder of a package.                                                                 | Narrow the paths, or move a file that both use to `shared`.                                                                                                                                          |
-| `ETAGFORMAT`             | `release-trains`          | A tag format does not contain `${version}` exactly once, or two trains share one, or the run tags with another format.                  | Give `--tag-format "<train>-v${version}"`, or `tagFormat` of the config.                                                                                                                             |
-| `ECHANGELOG`             | `release-trains`          | The changelog of a train has no place, or is a changelog of a package or of another train; or, of `file: false`, there is none.         | Give the train a `changelog` of its own, or `false`; of `file: false`, give the plugin `trainChangelog`.                                                                                             |
-| `ETRAINDEPENDSON`        | `release-trains`          | A `dependsOn` names no train, its own train, or a train that depends back on it.                                                        | Name other declared trains, and drop a name that makes a cycle. See [Dependency rules](dependency-rules.md).                                                                                         |
-| `EDEPENDENCYUNSATISFIED` | `release-trains`          | A package requires a version that no release of its train has.                                                                          | Release that train first, or require a released version.                                                                                                                                             |
-| `EDEPENDENCYNOTRAIN`     | `release-trains`          | A package depends, by a range that reaches the registry, on a package of no train.                                                      | Hold the folder of that package in the `paths` of a train, or drop the dependency.                                                                                                                   |
-| `EDEPENDENCYNORELEASE`   | `release-trains`          | A package depends, by a range that reaches the registry, on a package of a train that has no release.                                   | Release that train first.                                                                                                                                                                            |
-| `EDEPENDENCYUNRELEASED`  | `release-trains`          | A dependency train has unreleased commits (`fail`).                                                                                     | Release that train first.                                                                                                                                                                            |
-| `EECOSYSTEM`             | `release-trains`          | An ecosystem of `ecosystems` cannot be loaded, is no ecosystem, or has the name of another.                                             | Install it in the repo, or beside a global semantic-release, or name a file of it that is there; name each once.                                                                                     |
-| `EGIT`                   | `release-system`          | git failed, as in a shallow clone.                                                                                                      | Clone with all the history and the tags.                                                                                                                                                             |
-| `EWORKSPACE`             | `release-npm`             | A `package.json` of the workspace is not valid JSON.                                                                                    | Fix it, or leave its folder out of the workspace.                                                                                                                                                    |
-| `EGENERATED`             | `release-trains`          | A generated folder to list is not there.                                                                                                | List it after the build wrote it.                                                                                                                                                                    |
-| `EOPTIONS`               | `semantic-release-trains` | A run has no `trains` or no `ecosystems`, an option is not valid, as a `wrap` of no plugin, or an entry of both `wrap` and `generated`. | See [Configuring trains](configuring-trains.md).                                                                                                                                                     |
-| `EPLUGINLOAD`            | `semantic-release-trains` | The plugin an entry of `wrap` wraps cannot be loaded.                                                                                   | Install it in the repo, or beside a global semantic-release, or name a file of it that is there, by its path or its `file:` URL.                                                                     |
-| `ETAGNOTRELEASED`        | `semantic-release-trains` | The tag of a run of `semantic-release-trains-tag` is on no branch of the config, or on none of the channel it was released on.          | Push the branch with the tag, or fix semantic-release's note of the tag, `refs/notes/semantic-release-<tag>`.                                                                                        |
-| `EINFORUN`               | `semantic-release-trains` | The dry run of a train, which `semantic-release-trains-info` decides its release by, failed.                                            | Its log is above: run `RELEASE_TRAIN=<train> npx semantic-release --dry-run` to see it alone.                                                                                                        |
-| `EINFOVARIABLE`          | `semantic-release-trains` | Two trains make the same variables of `semantic-release-trains-info`, as `a-b` and `a_b`.                                               | Rename one of them, so their names differ in a letter or a digit.                                                                                                                                    |
-| `EPUBLISHER`             | `release-npm`             | The publisher cannot be loaded, or is not a publisher.                                                                                  | See [Publishing](publishing.md#publishers).                                                                                                                                                          |
-| `EPUBLISHCHECK`          | `release-npm`             | A package would not publish as it should.                                                                                               | Fix each fault in the list. Nothing was published.                                                                                                                                                   |
-| `EPUBLISHBEHIND`         | `release-npm`             | A release is below the version its dist-tag points at on the registry.                                                                  | Release forward. Nothing was published. Of a package npm pointed `latest` at on its first publish, on another channel, point it by hand; of one that joined at a higher version, name it in `aside`. |
-| `EPUBLISH`               | `release-npm`             | A publish, or a question to the registry, failed.                                                                                       | Fix the cause, delete the tag, run again at the release commit: see [Publishing](publishing.md#when-a-publish-fails).                                                                                |
-| `EREPLACE`               | `release-replace`         | The RegExp of a replacement is none.                                                                                                    | Give `from` the source of a RegExp, its backslashes doubled, and `flags` of no `g`.                                                                                                                  |
-| `ETEMPLATE`              | `release-replace`         | A replacement names a template that is none.                                                                                            | Define it in `templates`, of the root or of the entry, or name one the error lists.                                                                                                                  |
-| `EVALUE`                 | `release-replace`         | The text of a replacement names a value the context has not, or one of no text.                                                         | Name a value of text by its whole path, as `${nextRelease.version}`.                                                                                                                                 |
-| `EREPLACEFUNCTION`       | `release-replace`         | The function of a replacement gives no text.                                                                                            | Give each match a string, or a promise of one.                                                                                                                                                       |
-| `EREPLACEMODULE`         | `release-replace`         | The module of the function of a replacement cannot be loaded, or its export is no function.                                             | Name a module of the repo by its path, or a package it installs, and its export of a function.                                                                                                       |
-
-Each package exports its codes with what they mean: `SYSTEM_ERRORS` of
-`@wtf/release-system/errors`, `TRAINS_ERRORS` of `@wtf/release-trains/errors`, `PLUGIN_ERRORS` of
-`@wtf/semantic-release-trains/errors`, `NPM_ERRORS` of `@wtf/release-npm/errors`, and
-`REPLACE_ERRORS` of `@wtf/release-replace/errors`:
+Find your problem by what you see, under [Symptoms](#symptoms), or by the code that the run prints,
+under [Error codes](#error-codes). Each entry gives the cause, then the fix.
+
+## Symptoms
+
+### No release, but there are commits
+
+Check these causes in turn:
+
+- **The commits do not change the train's files.** The run logs how many commits since the last
+  release change the train's files. A commit of a file at the root, such as the lockfile, counts
+  only for the trains that list the file in `shared`. It also counts only when it changes no
+  train's own files. When it changes another train's files too, it counts for that train alone. See
+  [Which commits count](configuring-trains.md#which-commits-count).
+- **The commits do not make a release.** The commit analyzer decides, with its preset. With the
+  default rules, a `docs:` or `chore:` commit makes no release.
+- **A `!` is not read.** A tool that reads the commits with other parser options can read `feat!:`
+  as a minor release, or as no release. Give every breaking commit a `BREAKING CHANGE:` footer. See
+  [the caveat](configuring-trains.md#a-preset-and-type).
+- **A shallow clone.** A clone of one commit has no history and none of the trains' tags. Clone all
+  of the history: `GIT_DEPTH: 0` on GitLab, `fetch-depth: 0` on GitHub.
+
+### A train releases with no commits of its own
+
+**Cause:** A dependency train released a version outside a range that the train's last release
+published with `workspace:*`, `workspace:^` or `workspace:~`. For example, a peer dependency got a
+major release, or a dependency got a patch. The run logs each such release, and the notes list them
+in a `### Dependencies` section.
+
+**Fix:** This release is a cascade, and it is on by default. To turn it off, set `cascade: false` at
+the root of the config. See
+[Dependency rules](dependency-rules.md#when-a-dependency-train-releases-outside-a-published-range).
+
+### The version is too high
+
+**Cause:** A train's last release is its highest tag on the branch, in the train's tag format. A tag
+in another format, such as a `v1.2.0` from before the trains, is not read.
+
+**Fix:** To start a train from a version, tag a commit with that version in the train's tag format.
+
+### The notes list commits of another train
+
+**Cause:** A commit that changes the files of two trains is in the notes of both.
+
+**Fix:** When the notes must stay apart, split such a change into one commit for each train.
+
+### A squashed merge request releases several trains
+
+**Cause:** A squash commit holds all the changes of the merge request. It counts for each train
+whose files it changes. Its message decides the type of release for each of those trains.
+
+### The push is rejected
+
+**Cause:** Two runs pushed to the branch at the same time, or the job started from a commit that is
+behind the branch.
+
+**Fix:** Run the trains one at a time, and fetch the branch before each run. See
+[Run releases in CI](ci-recipes.md).
+
+## Error codes
+
+Every error of these packages is a `ReleaseError` from `@wtf/release-system/errors`, in the error
+class of its package: `TrainsError` from `@wtf/release-trains/errors`, or `ReplaceError` from
+`@wtf/release-replace/errors`. semantic-release prints them as it prints its own errors: the code,
+the message, and the details, which say how to fix it. A step that finds more than one fault reports
+all of them.
+
+When git fails, the error is `EGIT`, itself a `ReleaseError`. A validator of options from
+`@wtf/release-system` fails with `EOPTIONS`, or with the code its check gives, in the error class of
+the package that asks.
+
+This page lists the codes of the trains, npm and replace packages. The other packages describe their
+own codes:
+
+- Cargo: [Publish Cargo crates](publishing-crates.md).
+- Go: [Publish Go modules](publishing-go-modules.md).
+- Maven: [Publish Maven modules](publishing-maven.md).
+- `@wtf/release-validate`: [Validate a config](validating-a-config.md).
+- `EPUBLISHSMOKE` of `@wtf/release-npm`: [Publish npm packages](publishing.md).
+
+### `ETRAINNOTSELECTED`
+
+Package: `release-trains`.
+
+**Cause:** No train is chosen for the run.
+
+**Fix:** Set `RELEASE_TRAIN` in the job, or `train` at the root of the config.
+
+### `ETRAINUNKNOWN`
+
+Package: `release-trains`.
+
+**Cause:** The chosen train is not declared.
+
+**Fix:** Choose a declared train, or declare it.
+
+### `ETRAINNAME`
+
+Package: `release-trains`.
+
+**Cause:** A train's name cannot be part of a tag.
+
+**Fix:** Use only letters, digits, `.`, `_` and `-`.
+
+### `ETRAINPATHS`
+
+Package: `release-trains`.
+
+**Cause:** A train declares no paths.
+
+**Fix:** Give it `paths`.
+
+### `ETRAINOVERLAP`
+
+Package: `release-trains`.
+
+**Cause:** The paths of two trains hold the same file, or the same package's folder.
+
+**Fix:** Narrow the paths, or move a file that both trains use to `shared`.
+
+### `ETAGFORMAT`
+
+Package: `release-trains`.
+
+**Cause:** One of these:
+
+- A tag format does not contain `${version}` exactly once.
+- Two trains share one tag format.
+- The run tags with another format than the train's.
+
+**Fix:** Pass `--tag-format "<train>-v${version}"`, or set `tagFormat` in the config.
+
+### `ECHANGELOG`
+
+Package: `release-trains`.
+
+**Cause:** The train's changelog has no place. The train names no `changelog`, and its first path is
+a glob, so there is no folder for its `CHANGELOG.md`.
+
+**Fix:** Give the train a changelog of its own, such as `changelog: 'CHANGELOG-<train>.md'`, or
+`changelog: false` for none.
+
+### `ETRAINDEPENDSON`
+
+Package: `release-trains`.
+
+**Cause:** A `dependsOn` names no train, its own train, or a train that depends back on it.
+
+**Fix:** Name other declared trains, and drop a name that makes a cycle. See
+[Dependency rules](dependency-rules.md).
+
+### `EDEPENDENCYUNSATISFIED`
+
+Package: `release-trains`.
+
+**Cause:** A package requires a version that no release of its train has.
+
+**Fix:** Release that train first, or require a released version.
+
+### `EDEPENDENCYNOTRAIN`
+
+Package: `release-trains`.
+
+**Cause:** A package depends on a package that is in no train, by a range that reaches the registry.
+
+**Fix:** Put that package's folder in the `paths` of a train, or drop the dependency.
+
+### `EDEPENDENCYNORELEASE`
+
+Package: `release-trains`.
+
+**Cause:** A package depends on a package of a train that has no release, by a range that reaches
+the registry.
+
+**Fix:** Release that train first.
+
+### `EDEPENDENCYUNRELEASED`
+
+Package: `release-trains`.
+
+**Cause:** A dependency train has unreleased commits, and the config sets `dependencies: 'fail'`.
+
+**Fix:** Release that train first.
+
+### `EECOSYSTEM`
+
+Package: `release-trains`.
+
+**Cause:** An ecosystem in `ecosystems` cannot be loaded, is not an ecosystem, or has the same name
+as another.
+
+**Fix:** Install it in the repo or beside a global semantic-release, or name a file of it that is
+there. Name each ecosystem once.
+
+### `EGIT`
+
+Package: `release-system`.
+
+**Cause:** git failed, for example in a shallow clone.
+
+**Fix:** Clone all of the history and the tags.
+
+### `EWORKSPACE`
+
+Package: `release-npm`.
+
+**Cause:** A `package.json` in the workspace is not valid JSON.
+
+**Fix:** Fix it, or leave its folder out of the workspace.
+
+### `EGENERATED`
+
+Package: `release-trains`.
+
+**Cause:** A generated folder to list is not there.
+
+**Fix:** List it after the build has written it.
+
+### `EOPTIONS`
+
+Package: `semantic-release-trains`.
+
+**Cause:** One of these:
+
+- A run has no `trains` or no `ecosystems`.
+- An option is not valid, such as a `wrap` of no plugin.
+- An entry has both `wrap` and `generated`.
+
+**Fix:** See [Configure trains](configuring-trains.md).
+
+### `EPLUGINLOAD`
+
+Package: `semantic-release-trains`.
+
+**Cause:** The plugin that a `wrap` entry wraps cannot be loaded.
+
+**Fix:** Install it in the repo or beside a global semantic-release, or name a file of it that is
+there, by its path or its `file:` URL.
+
+### `ETAGNOTRELEASED`
+
+Package: `semantic-release-trains`.
+
+**Cause:** The tag of a `semantic-release-trains-tag` run is on no branch of the config, or on none
+of the channel it was released on.
+
+**Fix:** Push the branch with the tag, or fix semantic-release's note on the tag,
+`refs/notes/semantic-release-<tag>`.
+
+### `EINFORUN`
+
+Package: `semantic-release-trains`.
+
+**Cause:** A train's dry run failed. `semantic-release-trains-info` predicts the train's release
+with that dry run.
+
+**Fix:** The dry run's log is above the error. To see it alone, run
+`RELEASE_TRAIN=<train> npx semantic-release --dry-run`.
+
+### `EINFOVARIABLE`
+
+Package: `semantic-release-trains`.
+
+**Cause:** Two trains make the same variables of `semantic-release-trains-info`, such as `a-b` and
+`a_b`.
+
+**Fix:** Rename one of them, so that their names differ in a letter or a digit.
+
+### `EPUBLISHER`
+
+Package: `release-npm`.
+
+**Cause:** The publisher cannot be loaded, or is not a publisher.
+
+**Fix:** See [Publishing](publishing.md#publishers).
+
+### `EPUBLISHCHECK`
+
+Package: `release-npm`.
+
+**Cause:** A package would not publish as it should. Nothing was published.
+
+**Fix:** Fix each fault in the list.
+
+### `EPUBLISHBEHIND`
+
+Package: `release-npm`.
+
+**Cause:** A release is below the version that its dist-tag points at on the registry. Nothing was
+published.
+
+**Fix:** Release forward. Two cases need more:
+
+- npm pointed `latest` at a package on its first publish, on another channel: point it by hand.
+- A package joined the train at a higher version: name it in `aside`.
+
+### `EPUBLISH`
+
+Package: `release-npm`.
+
+**Cause:** A publish, or a question to the registry, failed.
+
+**Fix:** Fix the cause, delete the tag, and run again at the release commit. See
+[Publishing](publishing.md#when-a-publish-fails).
+
+### `EREPLACE`
+
+Package: `release-replace`.
+
+**Cause:** The RegExp of a replacement is not a valid RegExp.
+
+**Fix:** Give `from` the source of a RegExp, with its backslashes doubled, and `flags` without `g`.
+
+### `ETEMPLATE`
+
+Package: `release-replace`.
+
+**Cause:** A replacement names a template that does not exist.
+
+**Fix:** Define it in `templates`, at the root or in the entry, or name one that the error lists.
+
+### `EVALUE`
+
+Package: `release-replace`.
+
+**Cause:** The text of a replacement names a value that the context does not have, or a value that
+is not text.
+
+**Fix:** Name a value that is text by its whole path, such as `${nextRelease.version}`.
+
+### `EREPLACEFUNCTION`
+
+Package: `release-replace`.
+
+**Cause:** The function of a replacement returns no text.
+
+**Fix:** Return a string, or a promise of one, for each match.
+
+### `EREPLACEMODULE`
+
+Package: `release-replace`.
+
+**Cause:** The module of a replacement's function cannot be loaded, or its export is not a function.
+
+**Fix:** Name a module of the repo by its path, or a package that the repo installs, and an export
+that is a function.
+
+## Look up an error code in your code
+
+Each package exports its codes with what they mean:
+
+| Export           | Module                                |
+| ---------------- | ------------------------------------- |
+| `SYSTEM_ERRORS`  | `@wtf/release-system/errors`          |
+| `TRAINS_ERRORS`  | `@wtf/release-trains/errors`          |
+| `PLUGIN_ERRORS`  | `@wtf/semantic-release-trains/errors` |
+| `NPM_ERRORS`     | `@wtf/release-npm/errors`             |
+| `REPLACE_ERRORS` | `@wtf/release-replace/errors`         |
 
 ```ts
 import { REPLACE_ERRORS } from '@wtf/release-replace/errors'
@@ -64,48 +375,3 @@ export function describe(error: unknown): string {
   return `${MEANINGS[error.code] ?? error.message} ${error.details}`
 }
 ```
-
-## No release, but there are commits
-
-- **The commits do not change the files of the train.** The run logs how many commits since the
-  last release change the files of the train. A commit of a file at the root, such as the lockfile,
-  counts only for the trains that list the file in `shared`, and only when it changes the own files
-  of no train: beside the files of another train, it counts for that train alone. See
-  [Which commits count](configuring-trains.md#which-commits-count).
-- **The commits do not make a release.** The commit analyzer decides, with its preset. A `docs:` or
-  `chore:` commit makes no release with the default rules.
-- **A `!` is not read.** A tool that reads the commits with other parser options can read
-  `feat!:` as a minor release, or as no release. Give every breaking commit a `BREAKING CHANGE:`
-  footer. See [the caveat](configuring-trains.md#a-preset-and-type).
-- **A shallow clone.** A clone of one commit has no history and no tags of the trains. Clone with
-  all of the history: `GIT_DEPTH: 0` on GitLab, `fetch-depth: 0` on GitHub.
-
-## A release with no commits of its own
-
-A train releases when a dependency train released a version outside a range that the train's last
-release published, by `workspace:*`, `workspace:^` or `workspace:~`: a major of a peer, a patch of a
-dependency. The run logs each, and the notes have a section `### Dependencies` of them. Set
-`cascade: false` at the root of the config for none. See
-[Dependency rules](dependency-rules.md#a-release-of-a-dependency-train-that-a-published-range-does-not-take-a-cascade).
-
-## A version that is too high
-
-The last release of a train is its highest tag that the branch holds, in the tag format of the
-train. A tag of another format, such as a `v1.2.0` from before the trains, is not read. To start a
-train from a version, tag a commit in the format of the train.
-
-## The notes have commits of another train
-
-A commit that changes the files of two trains is in the notes of both. Split such a change into one
-commit for each train when the notes must stay apart.
-
-## A squashed merge request
-
-A squash commit holds all the changes of the merge request, and it counts for each train whose files
-it changes. Its message decides the type of release for each of those trains.
-
-## The push is rejected
-
-Two runs pushed to the branch at the same time, or the job started from a commit that is behind the
-branch. Run the trains one at a time, and fetch the branch before each run. See
-[CI recipes](ci-recipes.md).