@wtf/release-docs 8.2.1 → 8.2.3

package/guides/dependency-rules.md

@@ -1,21 +1,34 @@
-# Dependency rules
+# Trains that depend on other trains
+
+This page explains when a train depends on another train, what the plugins check before a release,
+and when a train releases because a train it depends on released. Read it to choose the order of
+your releases and to understand the errors the checks give.
 
 ## When a train depends on another
 
-Train `trains` depends on train `system` when a package whose folder is under the paths of `trains`
-depends on a package whose folder is under the paths of `system`, as `@wtf/release-trains` lists
-`@wtf/release-system`, by any kind but `dev`. The packages are those of the ecosystems of the root
-option `ecosystems`, the same rules for each: of `@wtf/release-npm`, each `package.json` git tracks,
-so one in `node_modules` counts for nothing, its `dependencies` and `optionalDependencies` what it
-runs with, its `peerDependencies` its users' peers, and its `devDependencies` what its own tests and
-tools run with, which orders no train and requires no version; of `@wtf/release-cargo`, each crate of
-the Cargo workspace at the root, its normal dependencies what it runs with, its build dependencies
-what its build runs with, and its dev-dependencies what its tests run with
-([Ecosystems](ecosystems.md)).
-
-A train also depends on each train that its `dependsOn` names. Use it for a train that must
-release after another one and lists none of its packages, such as a docs train whose reference
-shows the release of the trains that it documents:
+Train `trains` depends on train `system` when a package in `trains` depends on a package in
+`system`, by any kind of dependency except `dev`. For example, `@wtf/release-trains` lists
+`@wtf/release-system`. A package is in a train when its folder is under the train's paths.
+
+The packages come from the ecosystems that the root option `ecosystems` names. The same rules apply
+to each ecosystem:
+
+- `@wtf/release-npm` reads each `package.json` that git tracks, so a `package.json` in
+  `node_modules` does not count.
+  - `dependencies` and `optionalDependencies` are what the package runs with.
+  - `peerDependencies` are the peers that its users install.
+  - `devDependencies` are what its own tests and tools run with. They do not order trains, and they
+    require no version.
+- `@wtf/release-cargo` reads each crate of the Cargo workspace at the root.
+  - Normal dependencies are what the crate runs with.
+  - Build dependencies are what its build runs with.
+  - Dev-dependencies are what its tests run with.
+
+See [How ecosystems work](ecosystems.md) for every ecosystem.
+
+A train also depends on each train that its `dependsOn` names. Use `dependsOn` for a train that
+must release after another train but lists none of its packages. A docs train is an example: its
+reference shows the release of the trains that it documents.
 
 ```ts
 import type { Trains } from '@wtf/release-trains'
@@ -33,35 +46,54 @@ export const trains: Trains = {
 }
 ```
 
-A train that `dependsOn` names counts the same as a train that a package lists. The rule
-`dependencies` checks it, and a message names it `declared by dependsOn` where it would name the
-packages. It requires no version: only the range that a package lists does. When a package of the
-train already lists a package of the other train, the manifest says it, and `dependsOn` adds
-nothing. Use `dependsOn` only for an order that no `package.json` gives.
-
-`verifyConditions` fails with `ETRAINDEPENDSON` when a `dependsOn` names a train that the config
-does not declare, or the train itself. It also fails when the train that `dependsOn` names depends
-back on the train that names it, by its packages or by its own `dependsOn`, directly or through
-other trains: no order releases each of them after the other. A cycle of packages alone is not an
-error, and a `devDependency` of one train on a train that depends on it is none.
-
-Before `trains` releases, the plugins check each train that `trains` depends on: the trains plugin, in
-`verifyConditions`, that each package a range of a package of it requires is of a train, which has
-released, and that a release satisfies the range; and the commit analyzer an entry of
-`wrap` wraps, in `analyzeCommits`, that no such train has commits it has not released, by the rule
-`dependencies` of the root of the config: `warn` (the default), `fail` or `ignore`. The analyzer
-tells whether the commits would release the train, so the check runs where the analyzer is: once a
-run, by the first analyzer wrapped, however many the config wraps.
-
-## A required version that no release has: always an error
-
-When a package of `trains` that publishes requires a version range of a package of `system` that
-publishes, a release of `system` must satisfy the range, of any range that reaches the registry: of
-npm, of every field but `devDependencies`, which no consumer installs and the publish drops of a
-version no release has. A range of a package of no train fails the run with `EDEPENDENCYNOTRAIN`,
-and of a train with no release with `EDEPENDENCYNORELEASE`: no release gives it a version. When no
-tag of `system` names a version in the range, the run of `trains` fails with
-`EDEPENDENCYUNSATISFIED`, each whatever the option `dependencies` says:
+A train that `dependsOn` names counts the same as a train that a package lists. The `dependencies`
+rule checks it. Where a message would name the packages, it says `declared by dependsOn` instead.
+`dependsOn` requires no version: only a range that a package lists does.
+
+When a package of the train already lists a package of the other train, the manifest says so, and
+`dependsOn` adds nothing. Use `dependsOn` only for an order that no `package.json` gives.
+
+`verifyConditions` fails with `ETRAINDEPENDSON` in these cases:
+
+- A `dependsOn` names a train that the config does not declare, or the train itself.
+- The train that `dependsOn` names depends back on the train that names it, by its packages or by
+  its own `dependsOn`, directly or through other trains. No order can release each of them after
+  the other.
+
+A cycle of packages alone is not an error. Neither is a `devDependency` of one train on a train that
+depends on it.
+
+Before `trains` releases, the plugins check each train that `trains` depends on:
+
+- In `verifyConditions`, the trains plugin checks each range that a package of `trains` requires.
+  The package that the range names must be in a train, that train must have released, and a release
+  must satisfy the range.
+- In `analyzeCommits`, the commit analyzer that a `wrap` entry wraps checks that no such train has
+  commits it has not released. The root option `dependencies` decides what happens then: `warn`
+  (the default), `fail` or `ignore`.
+
+The analyzer tells whether the commits would release the train, so this check runs where the
+analyzer runs. It runs once a run, in the first wrapped analyzer, however many analyzers the config
+wraps.
+
+## When a required version has no release
+
+Some checks fail the run whatever the `dependencies` option says. They apply when a package of
+`trains` that publishes requires a version range of a package of `system` that publishes. A release
+of `system` must then satisfy that range.
+
+This holds for any range that reaches the registry. For npm, that is every field except
+`devDependencies`. No consumer installs a devDependency, and the publish drops one whose version no
+release has.
+
+| Error                    | When                                                                        |
+| ------------------------ | --------------------------------------------------------------------------- |
+| `EDEPENDENCYNOTRAIN`     | The range is on a package that is in no train.                              |
+| `EDEPENDENCYNORELEASE`   | The package's train has no release, so no release gives it a version.       |
+| `EDEPENDENCYUNSATISFIED` | No tag of `system` names a version in the range. The run of `trains` fails. |
+
+In this config, `dependencies: 'fail'` also fails the run of `trains` when `system` has commits that
+it has not released:
 
 ```js train=trains
 // release.config.mjs
@@ -85,52 +117,70 @@ export default {
 }
 ```
 
-The checks are `verifyTrain` and `unreleasedDependencies` of `@wtf/release-trains/verify`, which
-the plugins run with the commit analyzer of the config; a tool of its own runs them with its own.
-
-## What a package publishes
-
-The publish plugin resolves a `workspace:` range of a package of another train to the last release
-of that train, by its tags (`releasedVersions` of `@wtf/release-trains/packages`), as the package
-publishes. A train with no release fails it with `EDEPENDENCYNORELEASE`, before the tag, and a
-package of no train with `EDEPENDENCYNOTRAIN`. See [Publishing](publishing.md).
-
-## A release of a dependency train that a published range does not take: a cascade
-
-A train releases from its own commits. The publish resolves a `workspace:` range of a package of
-another train to that train's last release, so the manifest a release publishes holds that range
-until the train releases again. When the other train then releases a version outside it, as a major
-under `workspace:^`, or any release under `workspace:*`, a train with no commits of its own would
-never release, and its published manifest would keep the old range: a peer dependency fails the
-installs of the new version (`ERESOLVE`), and a dependency keeps its consumers on the old one.
-
-So the analyzer that an entry of `wrap` wraps releases the train of the dependency trains as well,
-by the option `cascade` of the root of the config, `true` by default. After it reads the type of
-release of the train's own commits, the plugin takes each package of the train, as the train's last
-release had it, at its tag, of each ecosystem, and that publishes, and each package of another
-train that it depends on by any kind but `dev`, of a range that reaches the registry: of npm, in
-`dependencies`, `peerDependencies` or `optionalDependencies`. Of each, the range that the last
-release published is the range its ecosystem resolves against the other train's last release then,
-its highest tag merged into the tag of the train's last release: of npm, a range that follows the
-version, `workspace:*`, `workspace:`, `workspace:^` or `workspace:~`, is of that version. When the
-other train's last release now, its highest tag merged into `HEAD`, is not in that range, the train
-cascades, by the kind the package depends on it by at `HEAD`, which its next release publishes, as
-a peer that is a dependency now:
-
-| Kind                                                    | The release it makes at least                         |
-| ------------------------------------------------------- | ----------------------------------------------------- |
-| A peer, of a major of the other train                   | `major`: its users must upgrade the peer past a major |
-| A peer, of a minor or a patch of the other              | `patch`: its users upgrade the peer within its major  |
-| What it runs with or builds by, as npm's `dependencies` | `patch`: the new manifest takes the new version       |
-
-A major of the other train is a release outside the `^` range of the one the published range was
-resolved against: `8.0.0` of `7.0.0`, `0.2.0` of `0.1.0`, `8.0.0-beta.1` of `7.0.0`. So an exact
-pin, `workspace:*`, that a minor of a peer has left, as `7.0.0` that `7.1.0` left, makes a patch
-that publishes `7.1.0`, not a major.
-
-The release is the higher of that type and the type of the train's own commits. The run logs each
-cascade, and the notes generator that an entry of `wrap` wraps has a section of them after its
-notes, whatever it writes, as:
+The checks are `verifyTrain` and `unreleasedDependencies` from `@wtf/release-trains/verify`. The
+plugins run them with the config's commit analyzer. A tool of your own can run them with its own
+analyzer.
+
+## Which version a published range takes
+
+When a package publishes, the publish plugin resolves each `workspace:` range on a package of
+another train to that train's last release. It reads that release from the train's tags
+(`releasedVersions` in `@wtf/release-trains/packages`).
+
+If the other train has no release, the publish fails with `EDEPENDENCYNORELEASE`, before the tag. A
+range on a package in no train fails it with `EDEPENDENCYNOTRAIN`. See
+[Publish npm packages](publishing.md).
+
+## When a dependency train releases outside a published range
+
+A train releases from its own commits. But the publish resolves a `workspace:` range on another
+train's package to that train's last release. So the manifest that a release publishes keeps that
+range until the train releases again.
+
+Suppose the other train then releases a version outside that range, such as a major under
+`workspace:^`, or any release under `workspace:*`. A train with no commits of its own would never
+release, and its published manifest would keep the old range:
+
+- A peer dependency makes installs of the new version fail (`ERESOLVE`).
+- A dependency keeps its consumers on the old version.
+
+So the analyzer that a `wrap` entry wraps also releases the train when this happens. This is a
+**cascade**. The root option `cascade` controls it, and it is `true` by default.
+
+After the analyzer reads the release type of the train's own commits, the plugin looks for
+cascades:
+
+1. It takes each package of the train that publishes, in each ecosystem, as the train's last
+   release had it at its tag.
+2. For each of those packages, it takes each package of another train that the package depends on
+   by any kind except `dev`, with a range that reaches the registry. For npm, that is a range in
+   `dependencies`, `peerDependencies` or `optionalDependencies`.
+3. It works out the range that the last release published. That is the range that the ecosystem
+   resolves against the other train's last release at that time: the other train's highest tag
+   that is merged into the tag of the train's last release. For npm, a range that follows the
+   version (`workspace:*`, `workspace:`, `workspace:^` or `workspace:~`) is a range of that
+   version.
+4. It finds the other train's last release now: its highest tag that is merged into `HEAD`. When
+   that release is not in the published range, the train cascades.
+
+The kind of dependency at `HEAD` sets the cascade's release type, because the next release
+publishes that kind. For example, a package that was a peer and is now a dependency counts as a
+dependency:
+
+| Kind                                                         | The release it makes at least                         |
+| ------------------------------------------------------------ | ----------------------------------------------------- |
+| A peer, of a major of the other train                        | `major`: its users must upgrade the peer past a major |
+| A peer, of a minor or a patch of the other train             | `patch`: its users upgrade the peer within its major  |
+| A dependency it runs or builds with, as npm's `dependencies` | `patch`: the new manifest takes the new version       |
+
+A major of the other train is a release outside the `^` range of the version that the published
+range was resolved against: `8.0.0` after `7.0.0`, `0.2.0` after `0.1.0`, `8.0.0-beta.1` after
+`7.0.0`. Take an exact pin, `workspace:*`, on a peer: it published `7.0.0`, and the other train
+then releases the minor `7.1.0`. That cascade makes a patch that publishes `7.1.0`, not a major.
+
+The release is the higher of the cascade's type and the type of the train's own commits. The run
+logs each cascade. The notes generator that a `wrap` entry wraps adds a section that lists them,
+after its own notes, whatever those notes are:
 
 ```md
 ### Dependencies
@@ -140,24 +190,26 @@ notes, whatever it writes, as:
 
 Nothing else cascades:
 
-- A train with no release yet: it published no range.
-- A dev-dependency, as a `devDependencies` range: no consumer installs it.
+- A train with no release yet: it has published no range.
+- A dev dependency, such as a `devDependencies` range: no consumer installs it.
 - A train that a `dependsOn` names: it requires no version.
-- A range of the author's own, as `^7.0.0` or `workspace:^7.0.0`: the publish writes it as it is,
-  so a release would publish the same range again. Widen it by a commit of the train.
+- A range that you wrote yourself, such as `^7.0.0` or `workspace:^7.0.0`: the publish writes it as
+  it is, so a release would publish the same range again. Widen it with a commit in the train.
 - A private package of the train: it publishes nothing.
-- A package of another train that the package no longer depends on at `HEAD`, by any kind but
-  `dev`, or a package that is no longer there: its next release publishes no range of it, so the
-  other train's release gives it no reason to release.
+- A package of another train that the package no longer depends on at `HEAD`, by any kind except
+  `dev`, or a package that no longer exists: the next release publishes no range for it, so the
+  other train's release gives no reason to release.
+
+A prerelease is in a range when it lies within the range's bounds, as semver's `includePrerelease`
+reads it. `7.1.0-beta.1` is in `^7.0.0`, so a prerelease of the next minor cascades no train under
+`^`. `8.0.0-beta.1` is not, so a prerelease of the next major cascades as the major would.
 
-A prerelease is in a range when it lies within its bounds, as semver's `includePrerelease` reads
-it: `7.1.0-beta.1` is in `^7.0.0`, so a prerelease of the next minor cascades no train under `^`,
-and `8.0.0-beta.1` is not, so a prerelease of the next major cascades as the major would. This reads
-compatibility, not what npm installs: npm installs a prerelease only for a range that names a
-prerelease of its own version, which a consumer on a prerelease channel asks for by the version.
+This reads compatibility, not what npm installs. npm installs a prerelease only for a range that
+names a prerelease of the same version, and a consumer on a prerelease channel asks for it by that
+version.
 
-The rule `dependencies` applies first: with `fail`, a dependency train with commits that it has not
-released fails the run before any cascade is read. `cascade: false` turns it off:
+The `dependencies` rule applies first. With `fail`, a dependency train with commits that it has not
+released fails the run before any cascade is read. `cascade: false` turns cascades off:
 
 ```js train=trains
 // release.config.mjs
@@ -181,14 +233,20 @@ export default {
 }
 ```
 
-The computation is `cascadesOf` of `@wtf/release-trains/cascade`, of the tag of the train's last
-release, with `cascadeType` and `cascadeNotes`; a tool of its own runs it with its own analyzer.
+`cascadesOf` in `@wtf/release-trains/cascade` computes the cascades from the tag of the train's
+last release, with `cascadeType` and `cascadeNotes`. A tool of your own can run it with its own
+analyzer.
+
+## Release the trains in order
+
+Release the trains in dependency order, by their packages and by `dependsOn`: each train before
+every train that depends on it. `trainOrder` in `@wtf/release-trains/packages` gives that order.
+For the trains in these guides, it releases `system` before `trains` and `replace`, and each of them
+before `docs`.
 
-## The order of the releases
+In CI, release the trains in that order, one at a time. Use one job that runs semantic-release once
+for each train, or a matrix whose jobs cannot run at the same time. See
+[Run releases in CI](ci-recipes.md).
 
-Release the trains in the order of their dependencies, of their packages and of `dependsOn`: a
-train before each train that depends on it. `trainOrder` of `@wtf/release-trains/packages` gives
-that order: `system` before `trains` and `replace`, and each before `docs`. In CI, release them
-in that order, one at a time: one job that runs semantic-release once for each, or a matrix whose
-jobs cannot run at the same time. See [CI recipes](ci-recipes.md). With `dependencies: 'fail'`, a
-run out of order fails. Run it again after the train that it depends on is released.
+With `dependencies: 'fail'`, a run out of order fails. Run it again after the train that it depends
+on has released.