@wtf/release-docs 9.1.0 → 10.0.0

package/guides/ecosystems.md

@@ -14,8 +14,13 @@ An ecosystem is a module that reads one kind of manifest, such as npm's `package
   depends on.
 - `satisfies` says whether a version is within a range, by the ecosystem's own rules.
 
-Five ecosystems are built in. Each one has a semantic-release plugin of its own that publishes its
-packages:
+An ecosystem that releases implements the steps of the contract of `@wtf/release/contract` too:
+`verify`, `prepare`, `smoke`, `publish` and `move`, each optional but `publish`. Any driver runs
+them, a semantic-release plugin, a CLI or a test, over a plan of the packages to publish (see
+[Release the packages](#release-the-packages)).
+
+Five ecosystems are built in, each one releasing by the contract, and each with a semantic-release
+plugin of its own that drives it:
 
 | Ecosystem | Package              | Plugin                        | Manifests it reads                                                                      |
 | --------- | -------------------- | ----------------------------- | --------------------------------------------------------------------------------------- |
@@ -70,8 +75,8 @@ ecosystem costs a repo nothing. For example, cargo's ecosystem gives no package
   a train (`EDEPENDENCYNOTRAIN`). That train must have released (`EDEPENDENCYNORELEASE`), and one
   of its releases must be within the range (`EDEPENDENCYUNSATISFIED`).
 - **Versions.** A release stamps each range on another train's package with that train's last
-  release, read from the train's tags that `HEAD` holds (`releasedVersions` of
-  `@wtf/release-trains/packages`).
+  release, read from the train's tags that `HEAD` holds. `planOf` of `@wtf/release-trains/plan`
+  gives them in the plan of the train, the version of each package of the repo.
 - **Cascade.** When another train's last release falls outside a range that this train's last
   release published, this train releases again. It releases a major when a major left a `peer`
   range behind, and a patch for any other kind.
@@ -107,8 +112,8 @@ See [Publish npm packages](publishing.md).
 
 `@wtf/release-cargo` reads the Cargo workspace at the root of the repo with
 `cargo metadata --no-deps --format-version 1`. For a commit, it exports the files with
-`git archive` into the system's temporary files, unpacks them with `tar`, reads them, and removes
-them.
+`git archive` into a temporary folder of the platform, unpacks them with `tar`, reads them, and
+removes them.
 
 - **Published:** every crate without `publish = false`.
 - **Kinds:** a normal dependency is `runtime`, a build dependency is `build`, and a dev-dependency
@@ -215,13 +220,13 @@ reads.
 
 ### The interface
 
-`@wtf/release-trains/ecosystem` declares the interface:
+`@wtf/release/ecosystem` declares the interface:
 
 ```ts fragment
 export interface Ecosystem {
   /** 'npm', 'cargo': as an error, the notes and a key of the trains say it. */
   readonly name: string
-  /** The packages of the repo, of the working tree, or at `context.ref`, by `context.system`. */
+  /** The packages of the repo, of the working tree, or at `context.ref`, of `context.root`. */
   packages(context: EcosystemContext): Promise<readonly Package[]>
   /** The range a release publishes of `range`, of `version`, the release of the package it names. */
   resolve(range: string, version: string): string
@@ -246,8 +251,8 @@ export interface Dependency {
 
 The trains call `packages` for the working tree, with no `ref`. They also call it for a commit, such
 as the tag of a train's last release, which a cascade reads. `packages` does everything through its
-context's `system`, as every library does: files, git, and the ecosystem's own tool. See
-[The system](system.md).
+context, as every library does: the files of the folder of the repo, `root`, and git and the
+ecosystem's own tool by the `platform`. See [The platform](platform.md).
 
 ### An example
 
@@ -256,9 +261,10 @@ of its own, a `release.json` in each folder. The manifest holds a name, a flag t
 package publishes, and dependencies at exact versions:
 
 ```ts
-import { git, gitOf, trackedFiles } from '@wtf/release-system/git'
-import { basenameOf, dirnameOf, joinPath } from '@wtf/release-system/posix'
-import type { Ecosystem, EcosystemContext, Package } from '@wtf/release-trains/ecosystem'
+import { readFile } from '@wtf/release/files'
+import { git, trackedFiles } from '@wtf/release/git'
+import { basenameOf, dirnameOf } from '@wtf/release/posix'
+import type { Ecosystem, EcosystemContext, Package } from '@wtf/release/ecosystem'
 
 /** What a release.json holds. */
 interface Manifest {
@@ -269,8 +275,7 @@ interface Manifest {
 
 /** Each release.json of the repo, of the working tree or of `context.ref`, by git. */
 async function manifestsOf(context: EcosystemContext): Promise<[string, Manifest][]> {
-  const { cwd, system } = gitOf(context)
-  const { ref } = context
+  const { root, ref } = context
   const files = (
     ref === undefined
       ? await trackedFiles(context)
@@ -280,7 +285,7 @@ async function manifestsOf(context: EcosystemContext): Promise<[string, Manifest
     files.map(async (file): Promise<[string, Manifest]> => {
       const text =
         ref === undefined
-          ? await system.fs.readFile(joinPath(cwd, file))
+          ? await readFile(root, file)
           : await git(['show', `${ref}:${file}`], context)
       return [file, JSON.parse(text) as Manifest]
     })
@@ -325,16 +330,29 @@ export default ecosystem
   such as `1.5.0-beta.1` for `^1.4.0`, because the trains release prereleases on their channels.
 - **No manifest means no package.** In a repo without any of the ecosystem's manifests, return `[]`
   rather than fail. A config can then name the ecosystem before the first manifest exists.
-- **Always use the system.** Do not use `node:*`, `process` or the global `fetch`. Everything the
-  module does outside itself goes through `context.system`. The trains can then run it on a CLI's
-  system, or on a test's system in memory.
+- **Always use the context.** Do not use `node:*`, `process` or the global `fetch`. Everything the
+  module does outside itself goes through `context.root` and `context.platform`. The trains can
+  then run it on a CLI's platform, or on a test's platform and folder in memory.
+
+### Release the packages
 
-### Publish the packages
+To release its packages too, the ecosystem implements `ReleasingEcosystem` of
+`@wtf/release/contract`, of options of its own: `publish`, and the steps of `verify`, `prepare`,
+`smoke` and `move` that fit it. Each step takes the `Release` (the version, the folder of the repo,
+the platform, whether it is a dry run, and where to log), the `Plan` of the ecosystem (its packages
+to publish, in order, and the version of each package of the repo), and its options. It knows no
+train: a driver gives it the plan, as `planOf` of `@wtf/release-trains/plan` works one out for a
+train, and runs a step of every ecosystem by `runStep` of `@wtf/release/driver`. The test ecosystem
+of `@wtf/release` (`packages/release/test/contract.test.ts`) implements every step, and each
+built-in library one, as the guide of each shows.
 
-The ecosystem does not publish. Write a semantic-release plugin for that, as
-`@wtf/semantic-release-npm`, `@wtf/semantic-release-cargo`, `@wtf/semantic-release-go` and
-`@wtf/semantic-release-maven` are. The plugin:
+A semantic-release plugin over it, as `@wtf/semantic-release-npm`, `-cargo`, `-go`, `-maven` and
+`-oci` are:
 
 - reads `trains`, `ecosystems` and `train` from the root of the config;
-- finds its train's packages with `ownersOf` from `@wtf/release-trains/packages`;
-- reads the other trains' versions with `releasedVersions`, which throws the trains' errors.
+- works out the plan of its train with `planOf`, which throws the trains' errors;
+- runs each step of the ecosystem in its step of semantic-release, on the platform and the folder of
+  the run that `runOf` of `@wtf/semantic-release` gives, marking the errors that leave it by
+  `markedStep`;
+- records what `publish` published for the links of the release, by `recordReleased` of
+  `@wtf/semantic-release/links`.

package/guides/getting-started.md

@@ -36,15 +36,16 @@ You can also write an ecosystem of your own for any other kind of package. See
 wtf release has two layers:
 
 - **Libraries** do the work. They do not depend on semantic-release or on any other release tool.
-  Each function takes the `system` it runs on from its caller, so you can also run the libraries
-  from a CLI or a script of your own. See [The system](system.md).
+  Each function takes the folder of the repo and the platform it runs on from its caller, so you
+  can also run the libraries from a CLI or a script of your own. See [The platform](platform.md).
 - **Plugins** let semantic-release run the libraries. Each plugin is a thin adapter over its
   library.
 
 The libraries:
 
-- `@wtf/release-system` is the base of the other libraries: the system, paths and globs, git,
-  option validators and `ReleaseError`. It knows nothing about trains.
+- `@wtf/release` is the base of the other libraries: the platform they run on, the files of the
+  repo, programs, paths and globs, git, option validators and `ReleaseError`. It knows nothing about
+  trains.
 - `@wtf/release-trains` handles the trains: their commits, their checks, and the folders a build
   generates.
 - `@wtf/release-npm`, `@wtf/release-cargo`, `@wtf/release-go`, `@wtf/release-maven` and
@@ -55,6 +56,8 @@ The libraries:
 
 The plugins:
 
+- `@wtf/semantic-release` is what every plugin shares: it makes Node's platform and the folder of
+  the repo for a run, and marks the libraries' errors for semantic-release.
 - `@wtf/semantic-release-trains` checks the trains, gives a plugin it wraps only the train's
   commits, and stages the folders a build generates.
 - `@wtf/semantic-release-npm`, `@wtf/semantic-release-cargo`, `@wtf/semantic-release-go`,
@@ -107,15 +110,14 @@ The examples in these guides use the trains that this repo releases its own pack
 
 | Train      | Folders                                                           |
 | ---------- | ----------------------------------------------------------------- |
-| `system`   | `packages/release-system`                                         |
+| `release`  | `packages/release`, `packages/semantic-release`                   |
 | `trains`   | `packages/release-trains`, `packages/semantic-release-trains`, …  |
 | `replace`  | `packages/release-replace`, `packages/semantic-release-replace`   |
 | `validate` | `packages/release-validate`, `packages/semantic-release-validate` |
 | `docs`     | `packages/docs`                                                   |
 
-`@wtf/release-trains` and `@wtf/release-replace` list `@wtf/release-system`, so `trains` and
-`replace` depend on `system`. `validate` depends on no other train. The docs package lists every
-package, so `docs` releases last.
+Each library lists `@wtf/release`, and each plugin `@wtf/semantic-release`, so `trains`, `replace`
+and `validate` depend on `release`. The docs package lists every package, so `docs` releases last.
 
 Each example shows only the trains it needs. The repo's own `release.config.mjs` declares them all,
 and tags each one `<train>-v<version>`. Here is a config with two trains:
@@ -192,7 +194,7 @@ releases nothing:
 RELEASE_TRAIN=trains npx semantic-release --dry-run --no-ci
 ```
 
-Release a train that another train depends on first, such as `system` before `trains`. The plugin
+Release a train that another train depends on first, such as `release` before `trains`. The plugin
 warns you when a dependency train has commits that it has not released. See
 [Trains that depend on other trains](dependency-rules.md).
 
@@ -214,7 +216,7 @@ copy of each package that it packs. See [Publish npm packages](publishing.md).
   train's tag on your host.
   Wrapped in the trains plugin, `@semantic-release/gitlab` links each package that the release
   published. See [The links of the release](publishing.md#the-links-of-the-release).
-- [The system](system.md): run the libraries on a system of your own.
+- [The platform](platform.md): run the libraries on a platform of your own.
 
 ## Make the first release
 

package/guides/platform.md

@@ -0,0 +1,179 @@
+# The platform
+
+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 programs.
+
+Every function of the libraries, such as `@wtf/release-trains`, `@wtf/release-npm` and
+`@wtf/release-replace`, reaches the outside world through two things its caller gives it:
+
+- `root`, the folder of the repo. It is a `FileSystemDirectoryHandle` of the File System standard,
+  so it can be a folder on disk, a folder in memory, or a browser's.
+- `platform`, what runs programs, fetches and makes temporary folders. It is a part of the platform
+  of [`@wtf/platform`](https://www.npmjs.com/package/@wtf/platform), picked to what the function
+  uses.
+
+The types come from `@wtf/release`, the base that the other libraries build on. A function requires
+them from its caller and never makes them itself. None of the library modules names Node. Each
+caller passes what fits it:
+
+- A semantic-release plugin passes Node's platform and the folder of the run.
+- A CLI passes Node's, or a platform of its own.
+- A test passes a platform and a folder in memory.
+
+Each function takes only what it uses:
+
+| It takes          | What it holds                                                                                               | Which functions take it                                           |
+| ----------------- | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
+| `root` alone      | The folder of the repo.                                                                                     | A function that only reads or writes files of the repo.           |
+| `RepoPlatform`    | `spawn`, which starts a program, `env`, the environment a program gets, and `dirs.cwd`, the working folder. | A function that runs git, or another program of the repo.         |
+| `ReleasePlatform` | A `RepoPlatform`, with `fetch`, and `path`, `navigator`, `crypto` and `dirs.temp` for temporary folders.    | A release that fetches, or stages what it packs outside the repo. |
+
+`platform.dirs.cwd` is the path of the folder that `root` is the handle of, and programs run there.
+`RepoContext` holds the two together, `{ root, platform }`:
+
+```ts
+import type { RepoContext } from '@wtf/release'
+import { readFile } from '@wtf/release/files'
+import { run } from '@wtf/release/process'
+
+/** The name of the root package, and the commit of the working tree. */
+export async function describe({ root, platform }: RepoContext) {
+  const { name } = JSON.parse(await readFile(root, 'package.json')) as { name: string }
+  const { stdout } = await run(platform, 'git', ['rev-parse', 'HEAD'])
+  return `${name}@${stdout.trim()}`
+}
+```
+
+`@wtf/release/files` reads and writes the files of a folder by their paths from it, with `/`:
+`readFile`, `readBytes`, `writeFile`, `exists`, `readDir`, `makeDir`, `remove` and `copy`.
+`@wtf/release/posix` joins paths without a platform.
+
+`run` of `@wtf/release/process` runs a program in the folder of the repo, or in a folder of it, and
+returns `{ stdout, stderr, code }`. The program gets the platform's `env`, or the environment you
+give it whole; `envOf` makes one of the platform's with variables of your own. A non-zero exit code
+is not a failure of `run` itself, and the caller decides what it means. `run` rejects only when the
+program cannot start.
+
+## Use Node's platform
+
+A CLI or a script on Node makes Node's platform with `nodePlatform` of
+`@wtf/platform-node/platform`, and the folder of the repo with `nodeDirectory` of
+`@wtf/platform-fs-node/handles`. Node's platform works in `process.cwd()` and gives each program
+`process.env`:
+
+```ts
+import type { ReleasePlatform } from '@wtf/release'
+import { readWorkspace } from '@wtf/release-npm/workspace'
+import { nodeDirectory } from '@wtf/platform-fs-node/handles'
+import { nodeStorage } from '@wtf/platform-fs-node/storage'
+import { nodePlatform } from '@wtf/platform-node/platform'
+
+const platform: ReleasePlatform = nodePlatform({
+  fetch: (input, init) => fetch(input, init),
+  storage: nodeStorage()
+})
+const root = await nodeDirectory(platform.dirs.cwd)
+
+export const packages = await readWorkspace(root)
+```
+
+## Write a platform of your own
+
+A CLI gives each function the platform it runs on, so it can change any member of it. This example
+logs each program before it runs:
+
+```ts
+import type { ReleasePlatform, RepoContext } from '@wtf/release'
+import npm from '@wtf/release-npm'
+import { verifyTrain } from '@wtf/release-trains/verify'
+
+/** A platform whose programs are logged before they run, over the one a CLI has. */
+export const logged = (platform: ReleasePlatform): ReleasePlatform => ({
+  ...platform,
+  spawn: (command, args, options) => {
+    console.error(`$ ${command} ${args.join(' ')}`)
+    return platform.spawn(command, args, options)
+  }
+})
+
+export function check({ root, platform }: RepoContext<ReleasePlatform>) {
+  return verifyTrain({
+    trains: {
+      validate: { paths: ['packages/release-validate', 'packages/semantic-release-validate'] }
+    },
+    train: 'validate',
+    ecosystems: [npm],
+    root,
+    platform: logged(platform)
+  })
+}
+```
+
+## The platform of the plugins
+
+Each plugin makes Node's platform and the folder of the repo for the run, with `runOf` of
+`@wtf/semantic-release`. It makes them from the folder and the environment that semantic-release
+gives each step, `cwd` and `env`, which the plugin requires. It passes them to every call into its
+library, so each program runs in that folder and with that environment.
+
+A plugin knows it runs on Node, and a library does not: a library always takes the platform it is
+given and assumes none. So a plugin has no option of its platform, and lays nothing over Node's. To
+change what the programs of a release see, change the environment of the run, as the variables of
+its job: `GIT_TERMINAL_PROMPT=0` stops every program of the release from asking for a password.
+
+A test of a plugin that runs it on a platform in memory mocks `@wtf/platform-node/platform`, as
+Vitest's `vi.mock` does, so the plugin's Node's platform is the test's.
+
+## Errors
+
+The libraries throw plain errors: each is a `ReleaseError` of `@wtf/release/errors`, or of a class
+of its package that extends it, with a stable code, a message of what is wrong, and details of how
+to fix it. They know nothing of the tool that prints them.
+
+A plugin marks them as they leave each of its steps, with `markedStep` of
+`@wtf/semantic-release/errors`, so that semantic-release prints each by its code, its message and
+its details. A CLI of your own prints them its own way:
+
+```ts
+import { isReleaseError } from '@wtf/release/errors'
+
+/** An error as a CLI prints it: its code and how to fix it, of a release's. */
+export const printed = (error: unknown): string =>
+  isReleaseError(error) ? `${error.code}: ${error.message}\n${error.details}` : String(error)
+```
+
+## Use a platform in tests
+
+A platform with scripted programs and a folder in memory run the libraries with no disk and no git.
+`memoryPlatform` of `@wtf/platform-memory/platform` answers each program by a script, and records
+each it runs. `memoryDirectory` of `@wtf/platform-fs-memory/handles` is a disk in memory:
+
+```ts
+import { testDirs } from '@wtf/platform/dirs'
+import { memoryDirectory } from '@wtf/platform-fs-memory/handles'
+import { memoryPlatform } from '@wtf/platform-memory/platform'
+import { makeDir, writeFile } from '@wtf/release/files'
+import npm from '@wtf/release-npm'
+
+// A disk in memory, of the folder of the repo, /repo, and a temporary folder, /tmp.
+const disk = memoryDirectory()
+const root = await makeDir(disk, 'repo')
+await makeDir(disk, 'tmp')
+await writeFile(root, 'package.json', '{ "name": "repo", "private": true }')
+await writeFile(root, 'packages/core/package.json', '{ "name": "@acme/core" }')
+
+// git lists the files it tracks. Any other program is not there, as of a command not found.
+const platform = memoryPlatform({
+  dirs: testDirs({ cwd: '/repo', temp: '/tmp' }),
+  directory: () => disk,
+  spawn: (command, args) =>
+    command === 'git' && args[0] === 'ls-files'
+      ? { stdout: 'package.json\0packages/core/package.json\0' }
+      : undefined
+})
+
+export const names = async () => (await npm.packages({ root, platform })).map(({ name }) => name) // ['repo', '@acme/core']
+
+// Each program that ran: [{ command: 'git', args: ['ls-files', '-z'], … }]
+export const runs = () => platform.spawn.runs
+```

package/guides/publishing-crates.md

@@ -94,21 +94,57 @@ and at the commit of a train's last release. For that commit, they export the fi
 
 ## What a release does
 
-1. **`verifyConditions`** checks the options and reads the workspace with `cargo metadata`. It
-   selects the crates that the release publishes and puts them in dependency order. It reads each
-   other train's last release from its tags. It checks the credentials. A workspace that cannot be
+The plugin maps each step of semantic-release onto a step of the cargo ecosystem, the contract of
+[`@wtf/release`](../../release/README.md). It gives the ecosystem the release, of the next
+release's version, and the train's plan: the train's crates that publish, in dependency order, and
+the version of each crate of the workspace, the release's for the train's crates and each other
+train's last release for that train's crates.
+
+1. **`verifyConditions`** checks the options and works out the plan, which reads the workspace with
+   `cargo metadata` and each other train's last release from its tags. A workspace that cannot be
    published fails here, before the tag (see
    [When crates depend on other trains](#when-crates-depend-on-other-trains)).
-2. **`prepare`** writes the versions into the manifests: the release's version into the train's
-   crates, and each other train's last release into that train's crates and into each dependency on
-   them. It then reads the workspace again. A crate that is not at its train's version fails the run
-   (see [What the stamp does not read](#what-the-stamp-does-not-read)).
-3. **`publish`** asks the registry's sparse index which crates it already has, and skips them. It
-   publishes the rest in dependency order with `cargo publish`. cargo waits for each crate to appear
-   in the index before the next one, so the crates of a release can install each other.
-
-A dry run of semantic-release runs only `verifyConditions`. It writes no version and publishes
-nothing.
+2. **`verifyRelease`** runs the ecosystem's `verify` once semantic-release knows the version: it
+   checks the version, the crates that the release publishes, of `include` and `exclude`, their
+   order, and the credentials.
+3. **`prepare`** runs the ecosystem's `prepare`, which writes the plan's versions into the
+   manifests: the release's version into the train's crates, and each other train's last release
+   into that train's crates and into each dependency on them. It then reads the workspace again. A
+   crate that is not at its train's version fails the run (see
+   [What the stamp does not read](#what-the-stamp-does-not-read)).
+4. **`publish`** runs the ecosystem's `publish`. It asks the registry's sparse index which crates
+   it already has, and skips them. It publishes the rest in the plan's order with `cargo publish`.
+   cargo waits for each crate to appear in the index before the next one, so the crates of a
+   release can install each other.
+
+A dry run of semantic-release runs only `verifyConditions` and `verifyRelease`. It writes no
+version and publishes nothing.
+
+### Without semantic-release
+
+The ecosystem knows no train and no release tool, so any driver can release the crates: give it a
+release and a plan, and run its steps, as with `runStep` of `@wtf/release/driver`. A dry run
+(`dryRun: true`) writes and publishes nothing: `prepare` gives the manifests it would write, and
+`publish` only asks the registry.
+
+```ts
+import type { Release } from '@wtf/release/contract'
+import { runStep } from '@wtf/release/driver'
+import { publishOrder } from '@wtf/release/order'
+import cargo from '@wtf/release-cargo'
+
+/** Every crate of the workspace that publishes, at the version of the release, but the docs. */
+export async function releaseCrates(release: Release) {
+  const packages = await cargo.packages(release)
+  const { order } = publishOrder(packages.filter(({ published }) => published))
+  const versions = new Map(order.map(({ name }) => [name, release.version]))
+  const plans = new Map([['cargo', { own: order, versions }]])
+  const ecosystems = [[cargo, { exclude: ['docs'] }]] as const
+  await runStep(release, plans, ecosystems, 'verify')
+  await runStep(release, plans, ecosystems, 'prepare')
+  return (await runStep(release, plans, ecosystems, 'publish')).released
+}
+```
 
 ## When crates depend on other trains
 
@@ -210,7 +246,10 @@ no release publishes it.
   before the tag with `EDEPENDENCYNORELEASE`.
 - **`publish = false` on what is not published.** Mark an example or a test crate of the workspace
   this way. Otherwise the train whose paths hold it publishes it. You can also leave a crate of the
-  train out with `exclude`, which names only crates of the train (`ECRATES`).
+  train out with `exclude`, which names only crates of the train, or crates that publish nowhere
+  (`ECRATES`). A crate with `publish = false` that a train's paths hold is stamped at the
+  train's version all the same, with its dependencies on published crates, so `cargo publish
+  --workspace` and the smoke, which build every member, resolve it.
 
 ## Authenticate to the registry
 
@@ -220,9 +259,9 @@ uses:
 - an ID token of the job, in `CRATES_IO_ID_TOKEN` by default (`idToken` names another variable);
 - a token, in `CARGO_REGISTRY_TOKEN`.
 
-With both, the plugin uses the ID token and the log says so. With neither, `verifyConditions` fails
-with `ECRATEAUTH` before the tag. A dry run only warns, because semantic-release runs only
-`verifyConditions` in a dry run.
+With both, the plugin uses the ID token and the log says so. With neither, `verifyRelease` fails
+with `ECRATEAUTH` before the tag. A dry run only warns so, because semantic-release runs neither
+`prepare` nor `publish` in a dry run.
 
 ### Trusted publishing
 
@@ -265,6 +304,8 @@ The plugin does the rest:
 - When the job ends, even when it fails, the plugin revokes the token (`DELETE` on the same URL). A
   failed revoke is logged and fails nothing, because the token expires by itself.
 - The tokens appear in no log and no error.
+- Each request to the registry names the library, `@wtf/release-cargo`, as its user agent, as
+  crates.io asks every client to name itself.
 
 A registry other than crates.io that offers the same exchange takes its API as `registryApi`, with
 its `registry` and its `index`:

package/guides/publishing-go-modules.md

@@ -10,7 +10,9 @@ or `v<version>` for a module at the root. The Go proxy reads the module from tha
 publishes a module by pushing its tag.
 
 The plugin runs on the library [`@wtf/release-go`](../../release-go/README.md). The library's
-default export is the Go ecosystem, and the plugin exports the same ecosystem at `./ecosystem`. Add
+default export is the Go ecosystem, which reads the modules of a repo and releases them in the steps
+of [`@wtf/release`](../../release/README.md)'s contract, and the plugin exports the same ecosystem
+at `./ecosystem`. Add
 `'@wtf/semantic-release-go/ecosystem'` to `ecosystems` in your config. The trains then treat modules
 the same way as npm packages: they decide which train holds each module, the order of the trains,
 the checks of a release, and the releases a train owes the trains it depends on. See
@@ -102,18 +104,24 @@ workflow:
 
 ## What a release does
 
-1. **`verifyConditions`** checks the options and reads the go.mod files that git tracks. It selects
-   the modules that the release tags, and reads each other train's last release from its tags. A
-   repo that cannot be released fails here, before the tag (see
+Each step of semantic-release runs a step of the Go ecosystem over the plan of the train: the
+modules of the train that Go can fetch, and the version of each module of the repo.
+
+1. **`verifyConditions`** checks the options and reads the go.mod files that git tracks. It works
+   out the plan of the train, which reads each other train's last release from its tags, and selects
+   the modules that the release tags. A repo that cannot be released fails here, before the tag (see
    [When modules depend on other trains](#when-modules-depend-on-other-trains)).
-2. **`verifyRelease`** checks each module's path against the major of the release's version
-   (`EGOMAJOR`; see [Release a new major](#release-a-new-major)).
-3. **`prepare`** checks the majors again and writes the versions into the go.mod files. It writes
+2. **`verifyRelease`** runs the ecosystem's `verify`. It checks that the version is one Go tags a
+   module of (`EGOSEMVER`), and each module's path against the major of the version (`EGOMAJOR`;
+   see [Release a new major](#release-a-new-major)).
+3. **`prepare`** runs the ecosystem's `prepare`, which writes the versions into the go.mod
+   files. It writes
    the release's version into each require of a module of the train, and each other train's last
    release into each require of that train's modules, in every go.mod of the repo. Then it reads the
    files again, and a require that is not at its train's version fails the run (`EGOVERSION`; see
    [What the release changes in go.mod](#what-the-release-changes-in-gomod)).
-4. **`publish`** commits the changed go.mod files and tags that commit with each module's tag (see
+4. **`publish`** runs `publish`, which commits the changed go.mod files and tags that commit with
+   each module's tag (see
    [Tag a commit that holds the versions](#tag-a-commit-that-holds-the-versions)). It skips each tag
    the remote already has. With `proxy`, it then asks the Go proxy for each module.
 
@@ -132,7 +140,8 @@ tag. The branch, the index and the working tree stay as they are; only the tags
 
 - The commit message is `chore(release): Go modules of <train> <version>`.
 - The author comes from `GIT_AUTHOR_NAME` and `GIT_AUTHOR_EMAIL`, and the committer from
-  `GIT_COMMITTER_*`. Without them, both are `semantic-release-bot`.
+  `GIT_COMMITTER_*`. Without them, both are `semantic-release-bot`. The plugin gives the library
+  this author: the library itself has none, and a caller of its own names one.
 - When no go.mod changed, as for modules that require no other module of the repo, the plugin tags
   the release commit itself.
 
@@ -190,8 +199,8 @@ From v2 on, Go holds the major in the module path: `example.com/repo/core/v2`. A
 `/vN` needs a release of major N. A release of major 2 or higher needs a path that ends in its
 major.
 
-The plugin checks this in `verifyRelease`, once semantic-release knows the version, and again in
-`prepare`. So a breaking change to a module whose path has no `/v2` fails before anything is tagged
+The plugin checks this in `verifyRelease`, once semantic-release knows the version. So a breaking
+change to a module whose path has no `/v2` fails before anything is tagged
 (`EGOMAJOR`). The error names the go.mod to change. In the commit of the breaking change:
 
 1. Write `module example.com/repo/core/v2` in that go.mod.
@@ -276,3 +285,38 @@ Before it creates anything, the plugin asks the remote for every tag. It skips e
 has, and pushes the rest in one atomic push: all of them or none. So retry the tag's job to create
 the missing tags. A remote that cannot be asked stops the run before anything is created
 (`EGOTAG`).
+
+## Release Go modules without semantic-release
+
+The Go ecosystem knows no train and no release tool. Any caller can release modules with it: give
+it a release, a plan, and its options, and run its steps, one by one or through `runStep` of
+`@wtf/release/driver`. The plan says which modules the release tags (`own`) and the version that
+each module of the repo is required at (`versions`). `@wtf/release-trains/plan` works out the plan
+of a train, or you can write one by hand.
+
+```ts
+import type { Plan, Release } from '@wtf/release/contract'
+import { runStep } from '@wtf/release/driver'
+import go from '@wtf/release-go'
+
+declare const release: Release
+declare const plan: Plan
+
+const plans = new Map([['go', plan]])
+const ecosystems = [
+  [
+    go,
+    {
+      remote: 'origin',
+      author: { name: 'Release Bot', email: 'release-bot@example.com' },
+      proxy: true
+    }
+  ]
+] as const
+await runStep(release, plans, ecosystems, 'verify')
+await runStep(release, plans, ecosystems, 'prepare')
+export const { released } = await runStep(release, plans, ecosystems, 'publish')
+```
+
+`publish` needs `remote` and `author`, unless the release is a dry run (`EGOTAG`). A dry run writes
+no go.mod, creates no commit and no tag, and asks the proxy nothing: it says the tags it would push.