@wtf/release-docs 8.1.0 → 8.2.0

package/guides/ecosystems.md

@@ -10,6 +10,8 @@ not. An **ecosystem** says those: a package of its own reads the manifests of on
 | --------- | -------------------- | ----------------------------- | ---------------------------------------------------- |
 | `npm`     | `@wtf/release-npm`   | `@wtf/semantic-release-npm`   | each `package.json` git tracks                       |
 | `cargo`   | `@wtf/release-cargo` | `@wtf/semantic-release-cargo` | the Cargo workspace at the root, by `cargo metadata` |
+| `go`      | `@wtf/release-go`    | `@wtf/semantic-release-go`    | each `go.mod` git tracks                             |
+| `maven`   | `@wtf/release-maven` | `@wtf/semantic-release-maven` | each `pom.xml` git tracks                            |
 
 A config names the ecosystems of the repo at its root, beside `trains`, each by the name of its
 module, whose default export is the ecosystem. It is required, and a repo of two kinds names both.
@@ -31,7 +33,7 @@ export default {
 ```
 
 The plugins load each of the repo, as an entry of `wrap` loads the plugin it wraps: by its name, its
-path from the repo (`./release/go.mjs`), or its `file:` URL. One that cannot be loaded, whose
+path from the repo (`./release/mine.mjs`), or its `file:` URL. One that cannot be loaded, whose
 default export is no ecosystem, or of the name of another, fails with `EECOSYSTEM`. An ecosystem
 that finds no manifest of its kind in the repo gives no package, so naming one more costs a repo
 nothing: cargo's gives none of a repo of no `Cargo.toml` at its root, and runs no `cargo`.
@@ -52,6 +54,10 @@ nothing: cargo's gives none of a repo of no `Cargo.toml` at its root, and runs n
 - **Cascade.** Where another train's last release has left a range the train's last release
   published, the train releases again: a major of a `peer` that a major left, a patch of any other
   kind.
+- **A train of none.** A publishing plugin of an ecosystem (`@wtf/semantic-release-npm`, `-cargo`,
+  `-go`, `-maven`) does nothing in a run of a train that holds none of that ecosystem's packages: it
+  says so in the log, and asks for no credential. So a config of several ecosystems lists each
+  plugin for every train, and a train of npm packages alone skips the crates.
 
 ## The interface
 
@@ -166,7 +172,7 @@ What to get right:
   itself is by `context.system`, so the trains run it on a CLI's system, or a test's in memory.
 
 The publishing is the ecosystem's own: a plugin of semantic-release of its own, as
-`@wtf/semantic-release-npm` and `@wtf/semantic-release-cargo` are, reads `trains`, `ecosystems` and
+`@wtf/semantic-release-npm`, `@wtf/semantic-release-cargo`, `@wtf/semantic-release-go` and `@wtf/semantic-release-maven` are, reads `trains`, `ecosystems` and
 `train` of the root, the packages of its train by `ownersOf` of `@wtf/release-trains/packages`, and
 the versions of the other trains by `releasedVersions`, which throws the errors of the trains.
 
@@ -203,30 +209,47 @@ is written as npm writes a range:
 
 See [Publishing crates](publishing-crates.md).
 
-## Sketches
+### Go
 
-Two ecosystems the trains could take, of the same interface: neither is a package yet.
+`@wtf/release-go` reads each `go.mod` git tracks, of the working tree or of a commit by `git show`,
+but those under a `vendor` or `testdata` folder. A package is named by its module path, of the
+`module` line; a go.mod of none, or two of one path, fail with `EGOMOD`. A module is published when
+Go can fetch it, as the first element of its path has a dot (`example.com/repo/core`, not `tools`).
+Each `require` of another module of the repo, of a line of its own or of a block, `// indirect` too,
+is `runtime`, Go's only kind, of the version it names, as `v0.0.0`. `resolve` is the version itself,
+of a `v`, as the stamp writes it (`v1.4.0`), and `satisfies` is Go's minimal version selection: the
+same major, and the same version or a later one, prereleases in the order of semver.
 
-### Go
+| requires | takes                     |
+| -------- | ------------------------- |
+| `v1.4.0` | `>=1.4.0, <2.0.0`         |
+| `v0.2.1` | `>=0.2.1, <1.0.0`         |
+| `v2.0.0` | `>=2.0.0, <3.0.0`         |
+| `latest` | none: it names no version |
 
-- **Packages:** the modules of `go.work`, each its `go.mod`; its folder is the module's.
-- **Dependencies:** each `require` of a sibling module is `runtime`, of the version it requires; a
-  `replace` by a path keeps the workspace building, and reaches no proxy.
-- **Publishing:** there is no registry. A release pushes Go's own tags, `<module dir>/vX.Y.Z`, beside
-  the train's tag, and the proxy reads them.
-- **`resolve` and `satisfies`:** the version itself; a version is within a requirement when it is at
-  least it, within its major, as minimal version selection reads it.
-- **A major:** from v2 on, the module's path ends in `/vN`, so a check of the release refuses a major
-  of a module whose path does not, until it changes.
+See [Publishing Go modules](publishing-go-modules.md).
 
 ### Maven
 
-- **Packages:** the modules of the reactor, each its `pom.xml`; a dependency on an artifact of
-  another module is one on a package of the repo.
-- **Kinds:** of its scope, `compile` and `runtime` are `runtime`, `provided` is `peer`, `test` is
-  `dev`, and a plugin of the build is `build`.
-- **The stamp:** each `0.0.0-SNAPSHOT` the release's version, and each version of a dependency on a
-  module of another train that train's last release.
-- **`resolve` and `satisfies`:** the version itself, of Maven's ranges (`[1.0,2.0)`) where an author
-  writes one.
-- **Publishing:** to Maven Central, each module of the train, signed, in the order of the reactor.
+`@wtf/release-maven` reads each `pom.xml` git tracks, of the working tree or of a commit by
+`git show`, but those in a `src` or a `target` folder, by a small XML reader of its own. A package
+is named `groupId:artifactId`, the groupId its parent's where the pom writes none. A module is
+published unless `maven.deploy.skip` is `true` in its `<properties>`, or in a parent's in the repo,
+its own value first. Its `<parent>` and each `<dependency>` of the scope `compile`, `runtime` or none
+are `runtime`, `provided` is `peer`, `test` is `dev` (of no range, as no consumer resolves it), and
+`system` is none; a `<dependencyManagement>` entry of the scope `import` is `runtime`, and a plugin of
+the build, or a plugin's dependency, `build`. The range is the `<version>` as written,
+`${project.version}` too. `resolve` is the version itself, as the stamp writes it, but a range of
+the author's own, which is itself; `satisfies` is Maven's rules, by Maven's order of versions:
+
+| pom          | takes                                     |
+| ------------ | ----------------------------------------- |
+| `1.4.0`      | any: a bare version is a soft requirement |
+| `[1.4,2.0)`  | `>=1.4.0, <2.0.0`                         |
+| `[1.4,)`     | `>=1.4.0`                                 |
+| `(,1.0]`     | `<=1.0.0`                                 |
+| `[1.4]`      | `1.4.0`                                   |
+| `[1,2),[3,)` | `>=1.0.0, <2.0.0`, or `>=3.0.0`           |
+
+So a bare version cascades nothing; a range of your own is never rewritten. See
+[Publishing Maven modules](publishing-maven.md).

package/guides/getting-started.md

@@ -9,15 +9,14 @@ There are two layers:
 
 - **The libraries**, of no release tool: `@wtf/release-system` (the system, paths, git, validators
   of options and `ReleaseError`, of no train, the base of the others), `@wtf/release-trains` (the
-  trains, their commits, their checks, the folders a build generates),
-  `@wtf/release-trains-changelog` (a changelog of each package), `@wtf/release-npm`
+  trains, their commits, their checks, the folders a build generates), `@wtf/release-npm`
   (every package of a train published), `@wtf/release-replace` (text replaced in files, as the
   version of a badge) and `@wtf/release-validate` (a config validated by any Standard Schema). Each
   function takes the `system` it runs by: see [The system](system.md).
 - **The plugins of semantic-release**, each a thin adapter over its library:
   `@wtf/semantic-release-trains` (the trains checked, a plugin given the train's commits alone, and
-  the folders a build generates staged), `@wtf/semantic-release-trains-changelog`,
-  `@wtf/semantic-release-npm` and `@wtf/semantic-release-replace`.
+  the folders a build generates staged), `@wtf/semantic-release-npm` and
+  `@wtf/semantic-release-replace`.
 
 ## Install
 
@@ -33,8 +32,7 @@ Each plugin is a package of its own, which semantic-release loads by its name, a
 it. `@wtf/semantic-release-trains` is one, which a config lists once for each role: of `wrap`, it
 gives the plugin it wraps, as the analyzer and the notes generator, the train's commits alone; of
 `generated`, it stages the folders a build generates; and every entry checks the trains. Install
-each other the config names: `@wtf/semantic-release-trains-changelog`,
-`@wtf/semantic-release-npm`, `@wtf/semantic-release-replace`. semantic-release brings
+each other the config names: `@wtf/semantic-release-npm`, `@wtf/semantic-release-replace`. semantic-release brings
 `@semantic-release/commit-analyzer` and `@semantic-release/release-notes-generator` with it, which
 an entry of `wrap` loads as semantic-release does.
 

package/guides/publishing-go-modules.md

@@ -0,0 +1,208 @@
+# Publishing Go modules
+
+A release train can release the Go modules of a repo beside its npm packages and crates: one
+version, one train tag, and a retry that finishes what stopped. Go has no registry to upload to. A
+version of a module is a git tag of its repo, `<folder>/v<version>`, or `v<version>` for a module at
+the root, and the Go proxy reads the module from that tag. The library is
+[`@wtf/release-go`](../../release-go/README.md), and the plugin over it
+[`@wtf/semantic-release-go`](../../semantic-release-go/README.md).
+
+`@wtf/release-go` is the ecosystem of Go too, its default export, which the plugin exports at
+`./ecosystem` and a config names in `ecosystems` as `'@wtf/semantic-release-go/ecosystem'`. The
+trains then read the modules of the repo as they read npm packages ([Ecosystems](ecosystems.md)):
+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.
+
+## The model
+
+The train tag is the version, and no version is written into git on the branch. Each go.mod that
+requires another module of the repo requires it at a placeholder, `v0.0.0`, and builds against the
+module in the repo by a `go.work` or a `replace` (see [go.work or replace](#gowork-or-replace)):
+
+```text
+module example.com/repo/cli
+
+go 1.24
+
+require example.com/repo/core v0.0.0
+```
+
+A module is each go.mod git tracks, but those under a `vendor` or `testdata` folder, which Go
+ignores. It is of the train whose `paths` hold its folder; the plugin reads `trains`, `ecosystems`
+and `train` of the root of the config, as `@wtf/semantic-release-npm` does. A module of no train is
+tagged by no release. A module whose path has no dot in its first element, as `module tools`, cannot
+be fetched by Go, so no release tags it, and a module that requires it fails before the tag
+(`EGOPRIVATE`). `ecosystems` must list the ecosystem of Go, or the plugin fails in
+`verifyConditions` with `EGOECOSYSTEM`:
+
+```js norun
+// release.config.mjs
+export const ecosystems = [
+  '@wtf/semantic-release-npm/ecosystem',
+  '@wtf/semantic-release-go/ecosystem'
+]
+```
+
+## The commit the tags name
+
+Go reads a module's go.mod at the commit its tag names, and uses the requires it finds there. The
+release commit of the branch still has the placeholders, so tagging it would publish
+`require example.com/repo/core v0.0.0`, a version that does not exist.
+
+So the run of the tag writes the versions into the go.mod files (`prepare`), then makes a commit of
+those files on top of the release commit, on no branch, and tags that commit with each module's tag
+(`publish`). The branch, the index and the working tree are left as they are; only the tags reach
+the remote. The commit is `chore(release): Go modules of <train> <version>`, of the author in
+`GIT_AUTHOR_NAME` and `GIT_AUTHOR_EMAIL` (and the committer in `GIT_COMMITTER_*`), else
+`semantic-release-bot`. When no go.mod changed, as for modules that require no other module of the
+repo, the release commit itself is tagged.
+
+The tag of a module in a folder of its major, as `example.com/repo/lib/v2` in `lib/v2`, is the folder
+above with the version, `lib/v2.0.0`, as Go looks it up.
+
+## Run it on the tag
+
+The branch run decides the version and pushes the train tag, as for any train. The run of the tag
+lists the plugin:
+
+```js norun
+// release.config.mjs
+export const tagPlugins = [
+  ['@wtf/semantic-release-trains', { wrap: '@semantic-release/release-notes-generator' }],
+  // The Go modules of the train of the run, whose `paths` hold their folders.
+  '@wtf/semantic-release-go',
+  ['@wtf/semantic-release-npm', { tarballDir: 'tarballs' }],
+  ['@semantic-release/gitlab', { successCommentCondition: false, failCommentCondition: false }]
+]
+```
+
+The plugin pushes its tags to the `repositoryUrl` of the run, which in a CI job holds the token
+semantic-release pushes by, so the job needs nothing more than the branch run does: `git`, and a
+token that may create the module tags. Where the tags of the repo are protected by a pattern that
+matches the module tags too, the token's role must be allowed to create them. The job needs no
+`go`, unless `proxy` is on.
+
+The module tags start pipelines of their own. Let a workflow rule run a pipeline for the train
+tags alone, and none for any other tag:
+
+```yaml
+workflow:
+  rules:
+    # The tag of a release of a train: its pipeline publishes.
+    - if: $CI_COMMIT_TAG =~ /^(core|cli)-v\d+\.\d+\.\d+/
+    # Every other tag, as a Go module's own (`core/v1.2.0`), runs no pipeline.
+    - if: $CI_COMMIT_TAG
+      when: never
+    - if: $CI_COMMIT_BRANCH
+```
+
+## Modules of several trains
+
+A repo can release its modules in several trains, each with its own version and tags: a core, and a
+CLI that requires it.
+
+```js norun
+// release.config.mjs
+export const trains = {
+  core: { paths: ['core'], shared: ['go.work'] },
+  cli: { paths: ['cli'], shared: ['go.work'] }
+}
+```
+
+The trains read the requires by the ecosystem of Go, so a train whose modules require another
+train's modules releases after it, as an npm package of one train that depends on a package of
+another does; no `dependsOn` says so.
+
+The release of a train writes its own version into each require of its modules, and the last
+release of each other train, of its tags that the tag's commit holds, into each require of that
+train's modules, in every go.mod of the repo. So the release `cli-v1.0.0`, after `core-v1.4.0`,
+tags `cli/v1.0.0` on a commit whose `cli/go.mod` has `require example.com/repo/core v1.4.0`, and
+tags nothing of core, whose `core/v1.4.0` the release of core made.
+
+The checks are the trains', before the tag: a module of the release that requires a module of no
+train fails with `EDEPENDENCYNOTRAIN`, and of a train that has no release with
+`EDEPENDENCYNORELEASE`, as neither has a version Go could fetch; a module the paths of two trains
+hold fails with `ETRAINOVERLAP`.
+
+Go's minimal version selection takes the version a module requires or a later one of the same
+major, so `require example.com/repo/core v1.4.0` takes core 1.5.0, and a release of core owes cli
+nothing ([Dependency rules](dependency-rules.md)). Core 2.0.0 is a module of another path (see
+[Majors](#majors)): cli takes it by changing its imports and its require, a change of cli's own,
+which releases cli.
+
+## Majors
+
+From v2 on, Go holds the major in the module path: `example.com/repo/core/v2`. A path that ends in
+`/vN` needs a release of major N, and a release of major 2 or more 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 of a module whose path has no `/v2` fails before anything is
+tagged (`EGOMAJOR`). The error names the go.mod to change: write `module example.com/repo/core/v2`
+there, and change each import and each require of the module to the new path, in the commit of the
+breaking change. A `gopkg.in/` path carries its major in its own way and is not checked.
+
+The module can stay in its folder (`core/go.mod`, tags `core/v2.0.0`), or move to a folder of its
+major (`core/v2/go.mod`, tags `core/v2.0.0` as well).
+
+## go.work or replace
+
+Before a release, each go.mod requires the modules of the repo at `v0.0.0`, which does not exist, so
+the build must find them in the repo. Two ways:
+
+- **go.work**, at the root, which lists the modules of the repo and is no part of any module:
+
+  ```text
+  go 1.24
+
+  use (
+  	./core
+  	./cli
+  )
+  ```
+
+  A build in the repo uses the modules of the workspace; a user's `go install` of a module reads its
+  go.mod alone, and never the repo's go.work.
+
+- **replace**, in each go.mod that requires a module of the repo:
+
+  ```text
+  require example.com/repo/core v0.0.0
+
+  replace example.com/repo/core v0.0.0 => ../core
+  ```
+
+  The release writes the version on the left of the replace too
+  (`replace example.com/repo/core v1.4.0 => ../core`), so it still applies to the version the
+  require names. But `go install example.com/repo/cli@v1.0.0` refuses a module whose go.mod has a
+  replace directive, so prefer go.work for a module people install by `go install`.
+
+A release changes only the version of each require of a module of the repo, and of each replace of
+one that names a version, where they stand: comments, layout and line endings stay. It does not
+touch go.sum and does not run `go mod tidy`. A go.sum needs no line for a module the build finds in
+the repo, by go.work or by a replace; and Go checks the modules a user fetches against its checksum
+database, not against the go.sum of the module that requires them. A require of a form the stamp
+does not read fails the run after it (`EGOVERSION`), so no go.mod is tagged at the wrong version.
+
+## The proxy
+
+`proxy: true` asks the Go proxy for each module once its tag is pushed, by
+`go list -m -json <path>@v<version>`, with `GOWORK=off`, `GOFLAGS=-mod=mod` and the `GOPROXY` of
+the job, Go's own by default. The proxy then has the version, and pkg.go.dev lists it; the release
+links to the first module there. It is off by default: the public proxy cannot fetch a private repo.
+Turn it on for a public repo, in a job that has `go`:
+
+```js norun
+// release.config.mjs
+export const go = ['@wtf/semantic-release-go', { proxy: true }]
+```
+
+A proxy that does not give a module fails the run with `EGOPROXY`, as when it lags a new tag; a
+retry of the job of the tag skips the tags the remote has and asks again. Users of a private repo
+set `GOPRIVATE` to its path, and fetch it by git instead of the proxy.
+
+## A release that stopped
+
+A tag the remote has stays: the checksum database records a module version the first time anyone
+fetches it, so a tag must never move. The plugin asks the remote for every tag before it makes
+anything, skips each it has, and pushes the rest in one atomic push, all or none. Retrying the job
+of the tag makes the tags that are missing. A remote that cannot be asked stops the run before
+anything is made (`EGOTAG`).

package/guides/publishing-maven.md

@@ -0,0 +1,293 @@
+# Publishing Maven modules
+
+A release train can deploy the modules of a Maven repo beside the packages of other ecosystems of the
+same release: one version, one tag, and a retry that finishes what stopped. A repo of several trains
+deploys each train's modules by its own release, and a module that depends on a module of another
+train at that train's last release. The library is
+[`@wtf/release-maven`](../../release-maven/README.md), and the plugin over it
+[`@wtf/semantic-release-maven`](../../semantic-release-maven/README.md). Neither reads a
+`package.json`: a module is a `pom.xml`, so the plugin is a plugin of its own, listed beside
+`@wtf/semantic-release-npm`, not a publisher of it.
+
+`@wtf/release-maven` is the ecosystem of Maven too, its default export, which the plugin exports at
+`./ecosystem` and a config names in `ecosystems` as `'@wtf/semantic-release-maven/ecosystem'`, so
+the trains read the modules of the repo by it, the same as the packages of npm
+([Ecosystems](ecosystems.md)): 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.
+
+Gradle is not covered: the plugin reads poms and runs `mvn`.
+
+## The model
+
+The tag is the version, and no version is written into git. Each `pom.xml` holds a placeholder,
+`0.0.0-SNAPSHOT`, as each `package.json` of an npm train holds `0.0.0-development`:
+
+```xml
+<project>
+  <parent>
+    <groupId>org.acme</groupId>
+    <artifactId>parent</artifactId>
+    <version>0.0.0-SNAPSHOT</version>
+    <relativePath>../parent/pom.xml</relativePath>
+  </parent>
+  <artifactId>client</artifactId>
+  <version>0.0.0-SNAPSHOT</version>
+
+  <dependencies>
+    <dependency>
+      <groupId>org.acme</groupId>
+      <artifactId>core</artifactId>
+      <version>0.0.0-SNAPSHOT</version>
+    </dependency>
+  </dependencies>
+</project>
+```
+
+The run of the tag writes the version of the tag into each pom, deploys, and the working tree is
+thrown away with the job. A module is each `pom.xml` git tracks, but one in a `src` or a `target`
+folder, as the fixtures of a plugin's tests; its name is `groupId:artifactId`, the groupId its
+parent's where it writes none.
+
+A module is of the train whose `paths` hold its folder, as a package is of the train whose paths
+hold its `package.json`; the plugin reads `trains`, `ecosystems` and `train` of the root of the
+config, as `@wtf/semantic-release-npm` does. A module of no train, as a sample, is deployed by no
+release. `ecosystems` must list the ecosystem of Maven, the plugin's
+`'@wtf/semantic-release-maven/ecosystem'` or `'@wtf/release-maven'`, or the trains read no module
+and the plugin fails in `verifyConditions` with `EMAVENECOSYSTEM`.
+
+A pom at the root of the repo has the folder `.`, which only a path of `.` holds, and that holds
+every file. Keep the parent in a folder of its own, as `parent/pom.xml`, and the root pom an
+aggregator of `<modules>`, of `maven.deploy.skip` and no train. Give each child the parent's
+`<relativePath>`, so Maven finds the parent in the repo rather than in a repository.
+
+## Run it on the tag
+
+The branch run decides the version and pushes the tag, as for any train. The run of the tag, the
+job that deploys, lists the plugin:
+
+```js norun
+// release.config.mjs
+export const tagPlugins = [
+  ['@wtf/semantic-release-trains', { wrap: '@semantic-release/release-notes-generator' }],
+  // The modules of the train of the run, whose `paths` hold their folders.
+  ['@wtf/semantic-release-maven', { args: ['-s', 'ci_settings.xml'] }],
+  ['@semantic-release/gitlab', { successCommentCondition: false, failCommentCondition: false }]
+]
+```
+
+The job needs Node, for semantic-release, and Maven and a JDK, for the deploys: an image of both, or
+one of them that installs the other. The jobs of the branch need neither Maven nor a JDK: the trains
+read the poms by git.
+
+The plugin deploys each module by `mvn -B -N -f <dir>/pom.xml deploy`, of that pom alone, from the
+root of the repo, after the modules it depends on. A deploy runs the build of the module and its
+tests; add `-DskipTests` to `args` where the branch pipeline has run them. A module the release needs
+to build, which it neither deploys nor finds on the repository, as a test kit of
+`maven.deploy.skip`, is installed into the local repository first.
+
+## Modules of several trains
+
+A repo can be released in several trains, each its own modules, version and tags, whose modules
+depend on the modules of the others: a core, a client over it, and docs over both.
+
+```js norun
+// release.config.mjs
+export const trains = {
+  core: { paths: ['parent', 'core'] },
+  client: { paths: ['client'] },
+  docs: { paths: ['docs'], dependsOn: ['core', 'client'] }
+}
+
+export const ecosystems = ['@wtf/semantic-release-maven/ecosystem']
+```
+
+The trains read the modules by the ecosystem of Maven, so a train whose modules depend on another
+train's modules, by any scope but `test`, or by a `<parent>` or a plugin of the build, releases after
+it; no `dependsOn` says so. Name a train in `dependsOn` only of what no pom says.
+
+The release of a train writes its own version into its modules, and the last release of each other
+train, of its tags that the tag's commit holds, into that train's modules and into everything that
+names them. So the release `client-v1.1.0`, after `core-v1.4.0`, deploys `client` 1.1.0 of the
+parent 1.4.0 and `core` 1.4.0, and nothing of core's, which the repository has.
+
+The checks are the trains', the same of every ecosystem, in `verifyConditions`, before the tag: a
+module of the release that depends on a module of no train fails with `EDEPENDENCYNOTRAIN`, and on a
+module of a train that has no release with `EDEPENDENCYNORELEASE`, as neither has a version a
+repository could serve, so the release never deploys the placeholder; a module the paths of two
+trains hold fails with `ETRAINOVERLAP`. A dependency of the `test` scope is no fault, as no consumer
+resolves it. A module of the release that depends on a module of `maven.deploy.skip`, by any other
+scope, or has it as its parent, fails with `EMAVENPRIVATE`: a consumer would not find it.
+
+### Versions and ranges
+
+A version Maven reads as a bare `<version>1.4.0</version>` is a soft requirement: Maven takes it
+unless the build has another version of the module. So a release of core of any version owes client
+nothing, and no train cascades of a bare version. A range of your own, as `[1.4,2.0)`, is by its
+bounds, in Maven's order of versions (`1.0` is `1.0.0`, `1.5.0-beta.1` comes before `1.5.0`): the
+release writes no range, and once core's last release is outside it, as 2.0.0, a release of client
+fails with `EDEPENDENCYUNSATISFIED` until you change the range.
+
+## What the stamp writes
+
+Each module takes the version of its train: of the train of the release, the release's; of another
+train, its last release; of no train, none. Of every pom of the repo, the stamp writes:
+
+- the project's `<version>` of each module that takes a version, a `${revision}` too;
+- the `<parent>`'s `<version>`, where the parent is a module of the repo that takes a version;
+- the `<version>` of each `<dependency>`, in `<dependencies>`, `<dependencyManagement>`, a plugin's
+  dependencies and a profile, and of each `<plugin>`, that names a module that takes a version,
+  `${project.version}` too.
+
+It leaves a range, a dependency of no `<version>`, which takes the one its `<dependencyManagement>`
+gives, and a version of a property of your own, as `${core.version}`: write the version of a module
+of the repo as `0.0.0-SNAPSHOT` or `${project.version}`. It writes no XML: it reads where each
+`<version>` is, and writes the new text there, so the comments, the layout and the line ends stay as
+they were.
+
+A module that writes no `<version>` takes its parent's, so it must be of the train of its parent: a
+module of another train, or whose parent is not of the repo, fails with `EMAVENSTAMP`; give it a
+`<version>0.0.0-SNAPSHOT</version>` of its own. A module of no train that inherits its version moves
+with its parent. After the stamp, the plugin reads the poms again, and a module not at the version
+of its train fails the run (`EMAVENVERSION`), so a pom the stamp did not write cannot deploy at the
+wrong version.
+
+## `maven.deploy.skip`
+
+A module whose `<properties>` set `maven.deploy.skip` to `true`, or whose parent in the repo does,
+is not deployed; its own value wins over its parent's, so a parent of samples can skip them all and
+one sample set it back to `false`. Use it for an aggregator, samples, integration tests and test
+kits. `exclude` leaves out a module of the train by its `groupId:artifactId` too.
+
+## The GitLab Maven registry
+
+The registry of a project serves its packages at
+`${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/maven`, and a job reads and writes it by its
+`CI_JOB_TOKEN`. The settings give Maven the token as the header `Job-Token`. They hold no secret, so
+commit them, or let the job write them:
+
+```xml
+<!-- ci_settings.xml -->
+<settings>
+  <servers>
+    <server>
+      <id>gitlab-maven</id>
+      <configuration>
+        <httpHeaders>
+          <property>
+            <name>Job-Token</name>
+            <value>${env.CI_JOB_TOKEN}</value>
+          </property>
+        </httpHeaders>
+      </configuration>
+    </server>
+  </servers>
+</settings>
+```
+
+The plugin is given the repository, its `url` of `${env.…}`, which it reads of the environment of
+the run, and the header its lookups send, which no log holds:
+
+```js norun
+// release.config.mjs
+export const maven = [
+  '@wtf/semantic-release-maven',
+  {
+    repository: {
+      id: 'gitlab-maven',
+      url: '${env.CI_API_V4_URL}/projects/${env.CI_PROJECT_ID}/packages/maven'
+    },
+    lookupAuth: { header: 'Job-Token', variable: 'CI_JOB_TOKEN' },
+    args: ['-s', 'ci_settings.xml']
+  }
+]
+```
+
+The same `<repository>` in the parent's `<distributionManagement>` serves as well, without
+`repository`. The registry is asked where it deploys, so `lookup` is not needed.
+
+## Maven Central
+
+Maven Central takes a release by the Central Portal, and serves it at
+`https://repo1.maven.org/maven2`. It needs each module signed, with a jar of its sources and one of
+its javadoc, a `<name>`, `<description>`, `<url>`, `<licenses>`, `<developers>` and `<scm>`, and a
+namespace (the groupId) the Portal has verified for you. Put the plugins in a profile `release`, so
+the branch builds do not sign:
+
+```xml
+<profile>
+  <id>release</id>
+  <build>
+    <plugins>
+      <plugin>
+        <artifactId>maven-source-plugin</artifactId>
+        <executions><execution><goals><goal>jar-no-fork</goal></goals></execution></executions>
+      </plugin>
+      <plugin>
+        <artifactId>maven-javadoc-plugin</artifactId>
+        <executions><execution><goals><goal>jar</goal></goals></execution></executions>
+      </plugin>
+      <plugin>
+        <artifactId>maven-gpg-plugin</artifactId>
+        <executions><execution><goals><goal>sign</goal></goals></execution></executions>
+      </plugin>
+      <plugin>
+        <groupId>org.sonatype.central</groupId>
+        <artifactId>central-publishing-maven-plugin</artifactId>
+        <extensions>true</extensions>
+        <configuration>
+          <publishingServerId>central</publishingServerId>
+          <autoPublish>true</autoPublish>
+          <waitUntil>published</waitUntil>
+        </configuration>
+      </plugin>
+    </plugins>
+  </build>
+</profile>
+```
+
+The `central-publishing-maven-plugin` takes the place of Maven's deploy, so a module needs no
+`distributionManagement`. The settings give it the user token of the Portal, of protected, masked
+variables:
+
+```xml
+<!-- ci_settings.xml -->
+<settings>
+  <servers>
+    <server>
+      <id>central</id>
+      <username>${env.CENTRAL_TOKEN_USERNAME}</username>
+      <password>${env.CENTRAL_TOKEN_PASSWORD}</password>
+    </server>
+  </servers>
+</settings>
+```
+
+The job imports the signing key before the release, as
+`echo "$GPG_PRIVATE_KEY" | gpg --batch --import`, and `maven-gpg-plugin` reads its passphrase of
+`MAVEN_GPG_PASSPHRASE`. The plugin asks Maven Central for each pom, which needs no credentials, and
+names no repository:
+
+```js norun
+// release.config.mjs
+export const maven = [
+  '@wtf/semantic-release-maven',
+  { lookup: 'https://repo1.maven.org/maven2', args: ['-s', 'ci_settings.xml', '-P', 'release'] }
+]
+```
+
+A deploy to the Portal is asynchronous: it is validated, then published, and only then served by
+`repo1.maven.org`. `waitUntil` `published` makes each deploy wait for it, so the next module finds
+the one before. A retry of a release before Maven Central serves a module deploys it again, and the
+Portal refuses a version it has: wait for the module to show, then retry. The OSSRH Staging API of
+the Portal, for builds on `maven-deploy-plugin`, is a `repository` of the plugin too, but it needs a
+call of its own after the deploys to move them to the Portal, which the plugin does not make.
+
+## A release that stopped
+
+A release version on a repository stays: Maven Central takes none twice, and a registry that takes
+one again gives two of the same version. The plugin asks the repository for the pom of each module
+before the first deploy (a `HEAD` request: a 2xx has it, a 404 lacks it), and skips each it has, so
+retrying the job of the tag deploys what is missing. A deploy that fails stops the run, with the code
+`EMAVENDEPLOY` and the tail of Maven's output; the modules before it are deployed. A repository that
+cannot be asked, or answers anything else, as a 401, stops the run before anything is deployed
+(`EMAVENREPOSITORY`): give `lookupAuth`, or a `lookup` that serves the poms to anyone.

package/guides/publishing.md

@@ -74,11 +74,12 @@ Of a publish in the release run itself, as below, semantic-release pushes the re
 publish that fails part way leaves both, and a run again
 finds that version released and does nothing. To finish it, delete the tag, on the remote and in the
 clone that runs again (a tag of the clone is a release done too), and run the release again at the release commit, the tip of the branch: semantic-release releases nothing
-of a commit behind the tip. The run computes the same version; `@wtf/semantic-release-trains-changelog`
-writes no section a changelog has already, so `@semantic-release/git` finds nothing to commit; it
-tags the release commit, skips each package that the registry already has, publishes the rest, and
-makes the release of the host. The stock `@semantic-release/changelog` would write the section
-again.
+of a commit behind the tip. The run computes the same version, tags the release commit, skips each
+package that the registry already has, publishes the rest, and makes the release of the host. A
+changelog plugin the trains plugin wraps finds the section of the release in the changelog already
+and skips its `prepare`, so `@semantic-release/git` finds nothing to commit. Listed unwrapped,
+`@semantic-release/changelog` writes the section again: wrap it, or remove the second section
+before the run.
 
 A retry of a job that runs at the commit of its pipeline, as a job of to-be-continuous does, runs
 behind the release commit. Check the tip out first, where it is the pipeline's commit with release