@wtf/release-docs 8.2.1 → 8.2.2

package/guides/publishing-maven.md

@@ -1,26 +1,28 @@
-# Publishing Maven modules
+# Publish 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/semantic-release-maven`](../../semantic-release-maven/README.md) deploys the Maven modules of
+a repo that belong to a train. Use it when a train holds Maven modules, alone or beside packages of
+other ecosystems in the same release. They share one version and one tag, and a retry finishes a
+release that stopped. In a repo with several trains, each train's release deploys its own modules.
+A module that depends on a module in another train gets that train's last release.
 
-`@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.
+The plugin runs on the library [`@wtf/release-maven`](../../release-maven/README.md). Neither of
+them reads a `package.json`: a module is a `pom.xml`. So the Maven plugin is a plugin of its own,
+listed beside `@wtf/semantic-release-npm`, and not a publisher for it. Gradle is not supported: the
+plugin reads poms and runs `mvn`.
 
-Gradle is not covered: the plugin reads poms and runs `mvn`.
+The library's default export is the Maven ecosystem, and the plugin exports the same ecosystem at
+`./ecosystem`. Add `'@wtf/semantic-release-maven/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 [How ecosystems work](ecosystems.md).
 
-## The model
+## Turn it on
 
-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`:
+### Keep a placeholder version in each pom
+
+The tag holds the version, and git holds no version. Each `pom.xml` keeps a placeholder,
+`0.0.0-SNAPSHOT`, as each `package.json` in an npm train keeps `0.0.0-development`:
 
 ```xml
 <project>
@@ -43,27 +45,38 @@ The tag is the version, and no version is written into git. Each `pom.xml` holds
 </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.
+The tag's run writes the tag's version into each pom and deploys. The job then throws the working
+tree away.
+
+A module is each `pom.xml` that git tracks, except one in a `src` or a `target` folder, such as the
+fixtures of a plugin's tests. Its name is `groupId:artifactId`. When the pom writes no groupId, the
+module takes its parent's.
+
+### Add the Maven ecosystem
+
+A module belongs to the train whose `paths` hold its folder, as a package belongs to the train
+whose paths hold its `package.json`. The plugin reads `trains`, `ecosystems` and `train` from the
+root of the config, as `@wtf/semantic-release-npm` does. No release deploys a module that belongs to
+no train, such as a sample.
 
-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`.
+`ecosystems` must list the Maven ecosystem: the plugin's `'@wtf/semantic-release-maven/ecosystem'`
+or `'@wtf/release-maven'`. Otherwise 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.
+### Keep the parent out of the root
 
-## Run it on the tag
+A pom at the root of the repo has the folder `.`. Only a path of `.` holds that folder, and such a
+path holds every file. So:
 
-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:
+- Keep the parent in a folder of its own, such as `parent/pom.xml`.
+- Make the root pom an aggregator of `<modules>`, with `maven.deploy.skip` and no train.
+- Give each child the parent's `<relativePath>`, so that Maven finds the parent in the repo rather
+  than in a repository.
+
+### List the plugin in the tag's run
+
+The branch run decides the version and pushes the tag, as for any train. The tag's run is the job
+that deploys. List the plugin there:
 
 ```js norun
 // release.config.mjs
@@ -75,20 +88,45 @@ export const tagPlugins = [
 ]
 ```
 
-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.
+### What the jobs need
+
+The tag's job needs Node for semantic-release, and Maven and a JDK for the deploys. Use an image
+with both, or one that has one of them and installs the other. The branch jobs need neither Maven
+nor a JDK, because the trains read the poms with git.
+
+## What a release does
 
-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.
+1. **`verifyConditions`** checks the options and reads the poms. It selects the modules that the
+   release deploys and puts them in dependency order. It reads each other train's last release from
+   its tags, and finds each module's repository. A repo that cannot be deployed fails here, before
+   the tag (see [When modules depend on other trains](#when-modules-depend-on-other-trains)).
+2. **`prepare`** writes the versions into the poms: the release's version into the train's poms,
+   and each other train's last release into that train's poms. It also writes them into the
+   parents, dependencies and plugins that name those modules. Then it reads the poms again, and a
+   module that is not at its train's version fails the run (see
+   [What the stamp writes](#what-the-stamp-writes)).
+3. **`publish`** asks each module's repository whether it has the module's pom, and skips each one
+   it has. It deploys the rest in dependency order.
 
-## Modules of several trains
+A dry run of semantic-release runs only `verifyConditions`. It writes no version and deploys
+nothing.
 
-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.
+### How a module is deployed
+
+The plugin deploys each module with `mvn -B -N -f <dir>/pom.xml deploy`. It builds that pom alone,
+from the root of the repo, after the modules it depends on.
+
+- A deploy runs the module's build and its tests. Add `-DskipTests` to `args` when the branch
+  pipeline has run them.
+- The release may need to build a module that it neither deploys nor finds on the repository, such
+  as a test kit with `maven.deploy.skip`. The plugin installs such a module into the local
+  repository first.
+
+## When modules depend on other trains
+
+A repo can be released in several trains. Each train has its own modules, version and tags, and its
+modules can depend on other trains' modules. For example: a core, a client over it, and docs over
+both.
 
 ```js norun
 // release.config.mjs
@@ -101,68 +139,91 @@ export const trains = {
 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 trains read the modules through the Maven ecosystem. A train whose modules depend on another
+train's modules releases after that train. Any scope except `test` counts, and so does a `<parent>`
+or a build plugin. You do not need `dependsOn` for this. Name a train in `dependsOn` only for what
+no pom says.
+
+### What versions the release writes
+
+A train's release writes its own version into its modules. For each other train, it writes the
+last release whose tag the tagged commit holds, into that train's modules and into everything that
+names them. For example, the release `client-v1.1.0` comes after `core-v1.4.0`. It deploys `client`
+1.1.0 with the parent at 1.4.0 and `core` at 1.4.0. It deploys nothing of core's, because the
+repository already has it.
+
+### Checks before the tag
 
-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 trains run the same checks for every ecosystem. They run in `verifyConditions`, before the tag:
 
-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.
+- A module of the release that depends on a module of no train fails with `EDEPENDENCYNOTRAIN`.
+- A module of the release that depends on a module of a train with no release fails with
+  `EDEPENDENCYNORELEASE`.
+- A module that the paths of two trains hold fails with `ETRAINOVERLAP`.
+
+In the first two cases there is no version that a repository could serve, so the release never
+deploys the placeholder. A dependency in the `test` scope is not a fault, because no consumer
+resolves it.
+
+A module of the release fails with `EMAVENPRIVATE` when it has a module with `maven.deploy.skip` as
+its parent, or depends on one in any scope but `test`. A consumer would not find that module.
 
 ### 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.
+Maven reads a bare version, such as `<version>1.4.0</version>`, as a soft requirement. Maven takes
+it unless the build has another version of the module. So no release of core owes client anything,
+and a bare version never causes a cascade (see
+[Trains that depend on other trains](dependency-rules.md)).
+
+A range of your own, such as `[1.4,2.0)`, works by its bounds, in Maven's order of versions: `1.0`
+is `1.0.0`, and `1.5.0-beta.1` comes before `1.5.0`. The release never writes a range. Once core's
+last release is outside your range, as 2.0.0 would be, 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:
+Each module takes its train's version. A module in the release's train takes the release's version.
+A module in another train takes that train's last release. A module of no train takes none. In every
+pom of the repo, the stamp writes:
+
+- the project's `<version>` of each module that takes a version, including a `${revision}`;
+- the `<parent>`'s `<version>`, when the parent is a module of the repo that takes a version;
+- the `<version>` of each `<dependency>` and each `<plugin>` that names a module that takes a
+  version, including `${project.version}`. This covers `<dependencies>`, `<dependencyManagement>`,
+  a plugin's dependencies, and profiles.
 
-- 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.
+The stamp leaves these alone:
 
-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 range;
+- a dependency without a `<version>`, which takes the one that its `<dependencyManagement>` gives;
+- a version from a property of your own, such as `${core.version}`.
 
-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.
+So write the version of a module of the repo as `0.0.0-SNAPSHOT` or `${project.version}`.
 
-## `maven.deploy.skip`
+The stamp does not rewrite the XML. It finds where each `<version>` is and writes the new text
+there, so comments, layout and line endings stay as they were.
 
-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.
+A module that writes no `<version>` takes its parent's, so it must be in its parent's train. A
+module in another train, or one whose parent is not in the repo, fails with `EMAVENSTAMP`. Give it
+its own `<version>0.0.0-SNAPSHOT</version>`. A module of no train that inherits its version moves
+with its parent.
 
-## The GitLab Maven registry
+After the stamp, the plugin reads the poms again. A module that is not at its train's version fails
+the run (`EMAVENVERSION`), so a pom that the stamp did not write cannot deploy at the wrong version.
 
-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
+## Skip a module with `maven.deploy.skip`
+
+The plugin does not deploy a module whose `<properties>` set `maven.deploy.skip` to `true`, or whose
+parent in the repo does. The module's own value wins over its parent's. So a parent of samples can
+skip them all, and one sample can set it back to `false`. Use it for an aggregator, samples,
+integration tests and test kits. You can also leave a module of the train out with `exclude`, by its
+`groupId:artifactId`.
+
+## Deploy to the GitLab Maven registry
+
+A project's registry serves its packages at
+`${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/maven`. A job reads and writes it with its
+`CI_JOB_TOKEN`. The settings give Maven the token as the `Job-Token` header. They hold no secret, so
 commit them, or let the job write them:
 
 ```xml
@@ -184,8 +245,8 @@ commit them, or let the job write them:
 </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:
+Give the plugin the repository and the header that its lookups send. The plugin reads each
+`${env.…}` in the repository's `url` from the run's environment. No log holds the header:
 
 ```js norun
 // release.config.mjs
@@ -202,16 +263,20 @@ export const maven = [
 ]
 ```
 
-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.
+The same `<repository>` in the parent's `<distributionManagement>` works as well, without
+`repository`. The plugin asks the registry where it deploys, so you do not need `lookup`.
+
+## Deploy to Maven Central
 
-## Maven Central
+Maven Central takes a release through the Central Portal, and serves it at
+`https://repo1.maven.org/maven2`. It needs:
 
-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:
+- each module signed;
+- a jar of the sources and a jar of the javadoc;
+- a `<name>`, `<description>`, `<url>`, `<licenses>`, `<developers>` and `<scm>`;
+- a namespace (the groupId) that the Portal has verified for you.
+
+Put the plugins in a `release` profile, so that the branch builds do not sign:
 
 ```xml
 <profile>
@@ -245,8 +310,8 @@ the branch builds do not sign:
 </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
+The `central-publishing-maven-plugin` replaces Maven's deploy, so a module needs no
+`distributionManagement`. The settings give it the Portal's user token, from protected, masked
 variables:
 
 ```xml
@@ -262,8 +327,8 @@ variables:
 </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
+Before the release, the job imports the signing key, as
+`echo "$GPG_PRIVATE_KEY" | gpg --batch --import`. `maven-gpg-plugin` reads its passphrase from
 `MAVEN_GPG_PASSPHRASE`. The plugin asks Maven Central for each pom, which needs no credentials, and
 names no repository:
 
@@ -275,19 +340,28 @@ export const maven = [
 ]
 ```
 
-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.
+A deploy to the Portal is asynchronous. The Portal validates it, then publishes it, and only then
+does `repo1.maven.org` serve it. `waitUntil` set to `published` makes each deploy wait for this, so
+the next module finds the one before it.
+
+If you retry a release before Maven Central serves a module, the plugin deploys that module again,
+and the Portal refuses a version it already has. Wait for the module to appear, then retry.
+
+The Portal's OSSRH Staging API, for builds on `maven-deploy-plugin`, can also be the plugin's
+`repository`. But it needs a call of its own after the deploys to move them to the Portal, and the
+plugin does not make that call.
+
+## When a publish fails
+
+A release version on a repository stays. Maven Central never takes a version twice, and a registry
+that takes one again ends up with two of the same version.
+
+Before the first deploy, the plugin asks the repository for each module's pom with a `HEAD`
+request: a 2xx means the repository has it, a 404 means it does not. The plugin skips each module
+the repository has, so retry the tag's job to deploy what is missing.
+
+- A deploy that fails stops the run with `EMAVENDEPLOY` and the tail of Maven's output. The modules
+  before it are deployed.
+- A repository that cannot be asked, or that answers anything else, such as a 401, stops the run
+  before anything is deployed (`EMAVENREPOSITORY`). Give `lookupAuth`, or a `lookup` that serves the
+  poms to anyone.