@wtf/release-docs 8.2.0 → 8.2.2

package/guides/publishing-crates.md

@@ -1,25 +1,29 @@
-# Publishing crates
+# Publish Cargo crates
 
-A release train can publish the crates of a Cargo workspace beside the npm packages of the same
-release: one version, one tag, and a retry that finishes what stopped. A workspace of several trains
-publishes each train's crates by its own release, and a crate that depends on a crate of another
-train at that train's last release. The libraries are
-[`@wtf/release-cargo`](../../release-cargo/README.md), and the plugin over it
-[`@wtf/semantic-release-cargo`](../../semantic-release-cargo/README.md). Neither reads a
-`package.json`: a crate is a package of `cargo metadata`, so the plugin is a plugin of its own,
-listed beside `@wtf/semantic-release-npm`, not a publisher of it.
+[`@wtf/semantic-release-cargo`](../../semantic-release-cargo/README.md) publishes the crates of a
+Cargo workspace that belong to a train. Use it when a train holds Rust crates, alone or beside npm
+packages in the same release. The crates and the packages share one version and one tag, and a
+retry finishes a release that stopped. In a workspace with several trains, each train's release
+publishes its own crates. A crate that depends on a crate in another train gets that train's last
+release.
 
-`@wtf/release-cargo` is the ecosystem of cargo too, its default export, which the plugin exports
-at `./ecosystem` and a config names in `ecosystems` as `'@wtf/semantic-release-cargo/ecosystem'`,
-so the trains read the crates of the repo by it, the same
-as the packages of npm ([Ecosystems](ecosystems.md)): which train holds each crate, 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-cargo`](../../release-cargo/README.md). Neither of
+them reads a `package.json`: a crate is a package that `cargo metadata` reports. So the cargo plugin
+is a plugin of its own, listed beside `@wtf/semantic-release-npm`, and not a publisher for it.
 
-## The model
+The library's default export is the cargo ecosystem, and the plugin exports the same ecosystem at
+`./ecosystem`. Add `'@wtf/semantic-release-cargo/ecosystem'` to `ecosystems` in your config. The
+trains then treat crates the same way as npm packages: they decide which train holds each crate,
+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 tag is the version, and no version is written into git. Each `Cargo.toml` of the workspace holds
-a placeholder, `0.0.0-development`, as each `package.json` of an npm train does, and `[workspace.package]`
-holds the version the crates of one train inherit:
+## Turn it on
+
+### Keep a placeholder version in each manifest
+
+The tag holds the version, and git holds no version. Each `Cargo.toml` in the workspace keeps a
+placeholder, `0.0.0-development`, as each `package.json` in an npm train does.
+`[workspace.package]` holds the version that the crates of one train inherit:
 
 ```toml
 [workspace.package]
@@ -29,22 +33,26 @@ version = "0.0.0-development"
 runtime = { path = "crates/runtime", version = "0.0.0-development" }
 ```
 
-A crate that depends on another by a path writes the `version` too, as a registry installs the
-crate by it and `cargo publish` refuses a path alone. The run of the tag writes the version of the
-tag into each, publishes, and the working tree is thrown away with the job.
+A crate that depends on another crate by a path writes the `version` too. A registry installs the
+crate by that version, and `cargo publish` refuses a path alone. The tag's run writes the tag's
+version into each manifest and publishes. The job then throws the working tree away.
+
+### Add the cargo ecosystem
 
-A crate 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 crate of no train, as an example or a tool, is
-published by no release. `ecosystems` must list the ecosystem of cargo, the plugin's
-`'@wtf/semantic-release-cargo/ecosystem'` or `'@wtf/release-cargo'`, or the trains read no crate
-and the plugin fails in `verifyConditions` with `ECARGOECOSYSTEM`: add it, as
+A crate 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 publishes a crate that belongs to no
+train, such as an example or a tool.
+
+`ecosystems` must list the cargo ecosystem: the plugin's `'@wtf/semantic-release-cargo/ecosystem'`
+or `'@wtf/release-cargo'`. Otherwise the trains read no crate, and the plugin fails in
+`verifyConditions` with `ECARGOECOSYSTEM`. Add it, as
 `ecosystems: ['@wtf/semantic-release-npm/ecosystem', '@wtf/semantic-release-cargo/ecosystem']`.
 
-## Run it on the tag
+### List the plugin in the tag's run
 
-The branch run decides the version and pushes the tag, as for any train. The run of the tag, the
-job that publishes, lists the plugin:
+The branch run decides the version and pushes the tag, as for any train. The tag's run is the job
+that publishes. List the plugin there:
 
 ```js norun
 // release.config.mjs
@@ -57,21 +65,44 @@ export const tagPlugins = [
 ]
 ```
 
-The order is the order of the registries: the crates first, then npm, then the release of the host.
-A crate depends on nothing of npm, and a package of npm may embed a build of the crates, so a
-release that fails in the crates publishes no npm package of a version whose crates are not there.
+The order follows the registries: crates first, then npm, then the GitLab or GitHub release. A crate
+depends on nothing in npm, and an npm package may embed a build of the crates. So when the crates
+fail, the release publishes no npm package whose crates are missing.
+
+### What the jobs need
+
+The tag's job needs `cargo` and a credential for the registry: see
+[Authenticate to the registry](#authenticate-to-the-registry).
 
-The job needs `cargo` and a credential for the registry, one of the two below. The jobs of the
-branch need `cargo` too, where `ecosystems` names cargo's and the repo has a `Cargo.toml` at its
-root: the trains read the crates by `cargo metadata`, of the working tree, and of the commit of the
-last release of a train, which they export by `git archive` into a temporary folder and unpack by
-`tar`.
+The branch jobs need `cargo` too, when `ecosystems` names the cargo ecosystem and the repo has a
+`Cargo.toml` at its root. The trains read the crates with `cargo metadata`, both in the working tree
+and at the commit of a train's last release. For that commit, they export the files with
+`git archive` into a temporary folder and unpack them with `tar`.
 
-## Crates of several trains
+## What a release does
 
-A workspace can be released in several trains, each its own crates, version and tags, whose crates
-depend on the crates of the others by a path: a runtime, codecs over it, and a client over both.
-Each crate names its dependencies by `[workspace.dependencies]`, of a path and the placeholder:
+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
+   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.
+
+## When crates depend on other trains
+
+A workspace can be released in several trains. Each train has its own crates, version and tags, and
+its crates can depend on other trains' crates by a path. For example: a runtime, codecs over it, and
+a client over both. Each crate names its dependencies in `[workspace.dependencies]`, with a path and
+the placeholder:
 
 ```toml
 [workspace.package]
@@ -84,10 +115,11 @@ codec = { path = "crates/codec", version = "0.0.0-development" }
 kafka = { path = "crates/kafka", version = "0.0.0-development" }
 ```
 
-The trains read the crates by the ecosystem of cargo, so a train whose crates depend on another
-train's crates, by a normal or a build dependency, releases after it, as an npm package of one train
-that depends on a package of another does; no `dependsOn` says so. Name a train in `dependsOn` only
-of what no crate says, as a docs train whose crate depends on none of them:
+The trains read the crates through the cargo ecosystem. A train whose crates depend on another
+train's crates, by a normal or a build dependency, releases after that train. This works as it does
+for an npm package that depends on a package in another train, and you do not need `dependsOn`. Name
+a train in `dependsOn` only for what no crate says, such as a docs train whose crate depends on none
+of them:
 
 ```js norun
 // release.config.mjs
@@ -101,82 +133,103 @@ export const trains = {
 export const ecosystems = ['@wtf/semantic-release-cargo/ecosystem']
 ```
 
-The release of a train writes its own version into its crates, and the last release of each other
-train, of its tags that the tag's commit holds, into that train's crates and into each dependency
-on them, as a `workspace:` range of an npm package of another train publishes that train's last
-release. So the release `kafka-v1.0.0`, after `runtime-v1.4.0` and `codecs-v2.1.0`, publishes
-`kafka` 1.0.0 of `runtime = "1.4.0"` and `codec = "2.1.0"`, and nothing of the others, which
-crates.io has. The crates of the other trains are written too, though not published, as cargo
-resolves a dependency by a path only of the version its crate is at.
-
-The checks are the trains', the same of every ecosystem, in `verifyConditions` of the plugin of the
-trains and of this plugin, before the tag: a crate of the release that depends on a crate of no
-train fails with `EDEPENDENCYNOTRAIN`, and on a crate of a train that has no release with
-`EDEPENDENCYNORELEASE`, as neither has a version crates.io could install, so the release never
-publishes the placeholder; a crate the paths of two trains hold fails with `ETRAINOVERLAP`. A
-dev-dependency of no `version` is no fault, as cargo drops it as it packages; one of a `version` is,
-as cargo keeps it. A dependency on a crate of `publish = false` is cargo's own fault,
-`ECRATEPRIVATE`, before the tag: of a normal or a build dependency, and of a dev-dependency of a
-`version`, which cargo keeps as it packages, so crates.io would refuse the crate in the middle of a
-release. A dev-dependency of no `version` on it is allowed, as cargo drops it.
-
-A release of a train the other trains' last releases leave behind is owed by them: a cascade
-([Dependency rules](dependency-rules.md)). The release publishes `version = "1.4.0"` of runtime
-1.4.0, which cargo reads as `^1.4.0`: runtime 1.5.0 is within it, and owes kafka nothing, but
-runtime 2.0.0 is not, so kafka's next release is at least a patch, of `runtime = "2.0.0"`, and its
-notes say so.
-
-### `[workspace.package]`
-
-`[workspace.package]` holds one version, so the crates of one train alone inherit it
-(`version.workspace = true`), and the crates of every other train set their own,
-`version = "0.0.0-development"` of their `[package]`, which their train's release writes. Where the
+### What versions the release writes
+
+A train's release writes its own version into its crates. For each other train, it writes the last
+release whose tag the tagged commit holds, into that train's crates and into each dependency on
+them. An npm package's `workspace:` range on another train works the same way. For example, the
+release `kafka-v1.0.0` comes after `runtime-v1.4.0` and `codecs-v2.1.0`. It publishes `kafka` 1.0.0
+with `runtime = "1.4.0"` and `codec = "2.1.0"`, and publishes nothing else, because crates.io
+already has the others. The release also writes the other trains' crates, without publishing them,
+because cargo resolves a path dependency only at the version its crate is at.
+
+### Checks before the tag
+
+The trains run the same checks for every ecosystem. They run in `verifyConditions` of the trains
+plugin and of this plugin, before the tag:
+
+- A crate of the release that depends on a crate of no train fails with `EDEPENDENCYNOTRAIN`.
+- A crate of the release that depends on a crate of a train with no release fails with
+  `EDEPENDENCYNORELEASE`.
+- A crate that the paths of two trains hold fails with `ETRAINOVERLAP`.
+
+In the first two cases there is no version that crates.io could install, so the release never
+publishes the placeholder. A dev-dependency without a `version` is not a fault, because cargo drops
+it when it packages the crate. A dev-dependency with a `version` is a fault, because cargo keeps it.
+
+A dependency on a crate with `publish = false` is cargo's own fault, `ECRATEPRIVATE`, also raised
+before the tag. It applies to a normal or a build dependency, and to a dev-dependency with a
+`version`, which cargo keeps when it packages. crates.io would refuse such a crate in the middle of
+a release. A dev-dependency on it without a `version` is allowed, because cargo drops it.
+
+### When another train's release leaves a crate behind
+
+When the other trains' last releases leave a train behind, that train owes a release: a cascade
+(see [Trains that depend on other trains](dependency-rules.md)). The release publishes
+`version = "1.4.0"` for runtime 1.4.0, which cargo reads as `^1.4.0`. Runtime 1.5.0 is within that
+range, so it owes kafka nothing. Runtime 2.0.0 is not, so kafka's next release is at least a patch,
+with `runtime = "2.0.0"`, and its notes say so.
+
+### Who inherits `[workspace.package]`
+
+`[workspace.package]` holds one version, so only the crates of one train can inherit it
+(`version.workspace = true`). The crates of every other train set their own
+`version = "0.0.0-development"` in their `[package]`, which their train's release writes. If the
 crates of two trains inherit it, or the crates of a train and a published crate of no train, the
-stamp fails with `ESTAMP` and names them. A crate of `publish = false` of no train, as an example,
-may inherit it too: it is at the version `[workspace.package]` takes, and no release publishes it.
+stamp fails with `ESTAMP` and names them. A crate with `publish = false` that belongs to no train,
+such as an example, may inherit it too. It is at the version that `[workspace.package]` holds, and
+no release publishes it.
 
 ## What crates.io needs
 
-- **A version of each dependency of a path.** `cargo publish` refuses a dependency of a path alone,
-  but a dev-dependency, which it drops: give each `version = "0.0.0-development"`, which the release
-  writes.
-- **What a crate says of itself.** crates.io takes no crate of no `description`, nor of no `license`
-  or `license-file`; give each crate the release publishes both, of its own `[package]` or of
-  `[workspace.package]` (`description.workspace = true`).
-- **A name and a publisher.** A crate's settings are its own, so a crate not on crates.io yet needs
-  a placeholder version before trusted publishing serves it ([Trusted publishing](#trusted-publishing)).
-- **Each dependency there first.** cargo waits for each crate it publishes to be in the index, and
-  the plugin publishes the crates of a train in the order of their dependencies, so the crates of a
-  release install each other. The crates of the other trains are there already: a release of one of
-  them fails before the tag, of `EDEPENDENCYNORELEASE`, where one is not.
-- **`publish = false` of what is not published.** An example or a test crate of the workspace says
-  so, or it is published by the train whose paths hold it. A crate of the train can be left out by
-  `exclude` too, which names only crates of the train (`ECRATES`).
-
-## Authenticate
-
-The plugin publishes by the credential the environment of the run has, and tells which is which:
-an ID token of the job (`CRATES_IO_ID_TOKEN` by default, `idToken` names another variable), or a
-token (`CARGO_REGISTRY_TOKEN`). With both, the ID token is used and the log says so. With neither,
-`verifyConditions` fails with `ECRATEAUTH` before the tag, a dry run excepted: semantic-release runs
-`verifyConditions` alone of one, so it only warns.
+- **A version on each path dependency.** `cargo publish` refuses a dependency with only a path,
+  except a dev-dependency, which it drops. Give each one `version = "0.0.0-development"`, which the
+  release writes.
+- **A description and a license.** crates.io refuses a crate without a `description`, or without a
+  `license` or `license-file`. Give each crate that the release publishes both, in its own
+  `[package]` or in `[workspace.package]` (`description.workspace = true`).
+- **A name and a publisher.** Each crate has its own settings on crates.io. A crate that is not on
+  crates.io yet needs a placeholder version before trusted publishing can serve it (see
+  [Trusted publishing](#trusted-publishing)).
+- **Each dependency there first.** cargo waits for each crate it publishes to appear in the index,
+  and the plugin publishes a train's crates in dependency order, so the crates of a release can
+  install each other. The other trains' crates are there already. If one is not, the release fails
+  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`).
+
+## Authenticate to the registry
+
+The plugin publishes with the credential that the run's environment has, and tells which one it
+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.
 
 ### Trusted publishing
 
-Recommended: the project holds no secret, as for npm. crates.io exchanges the ID token of a CI job
-for a publish token that lives a short while. It is in public beta on crates.io, and of GitLab.com
-only.
+Trusted publishing is the recommended way, because the project holds no secret, as with npm.
+crates.io exchanges the CI job's ID token for a short-lived publish token. It is in public beta on
+crates.io, and works only from GitLab.com.
+
+Set it up for each crate:
 
-In the settings of each crate on crates.io, add a GitLab publisher: the namespace and the project, the
-file path of the workflow that defines the publishing job (`.gitlab-ci.yml`, or the file that
-includes it, as crates.io's page for the field says), and, where the job names one, its environment.
-A setting is a crate's, so a crate that is not on crates.io yet needs a placeholder first, as an npm
-package does: publish `0.0.0` of it once with a token of the scopes `publish-new` and
-`publish-update`, of a description that says what the name is reserved for, then add the publisher and
-revoke the token. crates.io deletes no version, so the placeholder stays, and can be yanked; the first
-release of the train is a higher version.
+1. In the crate's settings on crates.io, add a GitLab publisher. Give the namespace and the project,
+   the file path of the workflow that defines the publish job, and the job's environment if it names
+   one. The file path is `.gitlab-ci.yml`, or the file that includes it, as crates.io's page for the
+   field explains.
+2. A crate that is not on crates.io yet has no settings, so it needs a placeholder first, as an npm
+   package does. Publish `0.0.0` of it once, with a token that has the scopes `publish-new` and
+   `publish-update`, and a description that says what the name is reserved for. Then add the
+   publisher and revoke the token. crates.io deletes no version, so the placeholder stays; you can
+   yank it. The train's first release is a higher version.
 
-The job asks GitLab for the ID token of the audience `crates.io`, and nothing else:
+The job asks GitLab for an ID token with the audience `crates.io`, and needs nothing else:
 
 ```yaml
 publish-release:
@@ -187,16 +240,20 @@ publish-release:
     - semantic-release-trains-tag
 ```
 
-The plugin does the rest. Before the first crate it publishes, it exchanges the ID token for a
-publish token (`POST https://crates.io/api/v1/trusted_publishing/tokens`) and gives it to `cargo`
-alone, as `CARGO_REGISTRY_TOKEN`, with the ID token out of `cargo`'s environment. When the job is
-done, a failed one too, it revokes the token (`DELETE` of the same URL). A release with nothing to
-publish exchanges nothing, so the token has the least time to expire. Where the registry
-refuses the token as expired, as in a long release, the plugin exchanges a new one, once, and tries the
-crate again. The tokens are in no log and no error. A revoke that fails is logged and fails nothing:
-the token expires by itself.
+The plugin does the rest:
+
+- Before the first crate it publishes, it exchanges the ID token for a publish token
+  (`POST https://crates.io/api/v1/trusted_publishing/tokens`). It gives the publish token only to
+  `cargo`, as `CARGO_REGISTRY_TOKEN`, and keeps the ID token out of `cargo`'s environment.
+- A release with nothing to publish exchanges nothing. Exchanging late leaves the token the least
+  time to expire.
+- If the registry refuses the token as expired, as in a long release, the plugin exchanges a new
+  one, once, and tries the crate again.
+- 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.
 
-A registry that is not crates.io, and offers the same exchange, takes its API as `registryApi`, with
+A registry other than crates.io that offers the same exchange takes its API as `registryApi`, with
 its `registry` and its `index`:
 
 ```js norun
@@ -213,29 +270,37 @@ export const cargo = [
 
 ### A token
 
-An API token of crates.io, scoped to `publish-new` and `publish-update` and to the crates of the
-train, kept as a protected, masked variable `CARGO_REGISTRY_TOKEN` of the group or the project, so
-only the pipeline of a protected tag reads it. Nothing else is needed, and it works on any CI, of
-a registry that has no trusted publishing too (`CARGO_REGISTRIES_<NAME>_TOKEN` of a `registry` that
-is not crates.io). It is a long-lived secret: rotate it, and drop it once trusted publishing serves.
+Create a crates.io API token with the scopes `publish-new` and `publish-update`, limited to the
+train's crates. Keep it as a protected, masked variable `CARGO_REGISTRY_TOKEN` of the group or the
+project, so that only the pipeline of a protected tag can read it. You need nothing else. It works
+on any CI, and with a registry that has no trusted publishing too: use
+`CARGO_REGISTRIES_<NAME>_TOKEN` for a `registry` that is not crates.io. The token is a long-lived
+secret. Rotate it, and drop it once trusted publishing works.
 
-## A release that stopped
+## When a publish fails
 
-A published crate version stays: crates.io takes none twice, and a yanked one stays taken. The
-plugin asks the registry's sparse index of each crate before the first publish, and skips each it
-has, so retrying the job of the tag publishes what is missing. A publish cargo fails because the
-version is there already, as when the index had not caught up with an earlier run, is skipped once
-the registry, asked again over half a minute, says it has it. A crate that fails stops the run,
-with the code `ECRATEPUBLISH` and the tail of cargo's output; the crates before it are published.
-A registry that cannot be asked stops the run before anything is published (`ECRATESIO`).
+A published crate version stays: crates.io never takes a version twice, and a yanked version stays
+taken. Before the first publish, the plugin asks the registry's sparse index about each crate and
+skips each crate the registry has. So retry the tag's job to publish what is missing.
+
+- If cargo fails because the version is there already, as when the index had not caught up with an
+  earlier run, the plugin asks the registry again for up to half a minute. Once the registry has the
+  crate, the plugin skips it.
+- A crate that fails stops the run with `ECRATEPUBLISH` and the tail of cargo's output. The crates
+  before it are published.
+- A registry that cannot be asked stops the run before anything is published (`ECRATESIO`).
 
 ## What the stamp does not read
 
-The stamp is a line editor, not a TOML parser, so the manifests keep their comments and their
-layout. A dependency renamed by `package = "…"` of `[workspace.dependencies]` is not read; an
-inline table of several lines, and a dependency on a crate of a train written by dotted keys
-(`name.path = "…"`), fail with `ESTAMP`. A crate of no train, or of a train with no release, keeps
-its version, and the dependencies on it are left; the dependencies of every crate on the crates of
-the trains are written, so the workspace still builds. After it, the plugin reads the workspace
-again, and a crate not at the version of its train fails the run (`ECRATEVERSION`), so a manifest
-that the stamp did not write cannot publish at the wrong version.
+The stamp edits lines; it does not parse TOML. So the manifests keep their comments and their
+layout. It has these limits:
+
+- It does not read a dependency renamed with `package = "…"` in `[workspace.dependencies]`.
+- An inline table that spans several lines fails with `ESTAMP`.
+- A dependency on a train's crate written with dotted keys (`name.path = "…"`) fails with `ESTAMP`.
+
+A crate of no train, or of a train with no release, keeps its version, and the dependencies on it
+stay as they are. The stamp writes every crate's dependencies on the trains' crates, so the
+workspace still builds. After the stamp, the plugin reads the workspace again. A crate that is not
+at its train's version fails the run (`ECRATEVERSION`), so a manifest that the stamp did not write
+cannot publish at the wrong version.