@wtf/release-docs 8.2.0 → 8.2.2

package/guides/ecosystems.md

@@ -1,25 +1,40 @@
-# Ecosystems
-
-The trains read no manifest. Which train holds each package, the order the trains release in, the
-checks of a release, and the releases a train owes the trains it depends on are the same for every
-kind of package; what a package is, what it depends on, and what a range of versions means, are
-not. An **ecosystem** says those: a package of its own reads the manifests of one kind, as npm's
-`package.json` or cargo's `Cargo.toml`, gives the trains their packages, and publishes them.
-
-| Ecosystem | Its package          | Its plugin                    | Its manifests                                        |
-| --------- | -------------------- | ----------------------------- | ---------------------------------------------------- |
-| `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.
-Each plugin exports its ecosystem at `./ecosystem`, as `'@wtf/semantic-release-npm/ecosystem'`,
-so a config names the plugin it installs and nothing more; the package of the ecosystem,
-`'@wtf/release-npm'`, is the same ecosystem, for a repo that installs it. A global install of
-semantic-release, as the semantic-release component of to-be-continuous makes, finds the plugin's
-alone: it puts the package of the ecosystem in the plugin's own node_modules.
+# How ecosystems work
+
+The trains do not read manifests themselves. Much of their work is the same for every kind of
+package: which train holds each package, the order the trains release in, the checks of a release,
+and the releases a train owes the trains it depends on. Other things differ between kinds of
+package: what a package is, what it depends on, and what a version range means. An **ecosystem**
+supplies those parts.
+
+An ecosystem is a module that reads one kind of manifest, such as npm's `package.json` or cargo's
+`Cargo.toml`, and gives the trains their packages. It has a name and three functions:
+
+- `packages` lists the repo's packages and their dependencies.
+- `resolve` returns the range that a release publishes for a dependency, given the version it
+  depends on.
+- `satisfies` says whether a version is within a range, by the ecosystem's own rules.
+
+Four ecosystems are built in. Each one has a semantic-release plugin of its own that publishes its
+packages:
+
+| Ecosystem | Package              | Plugin                        | Manifests it reads                                        |
+| --------- | -------------------- | ----------------------------- | --------------------------------------------------------- |
+| `npm`     | `@wtf/release-npm`   | `@wtf/semantic-release-npm`   | each `package.json` that git tracks                       |
+| `cargo`   | `@wtf/release-cargo` | `@wtf/semantic-release-cargo` | the Cargo workspace at the root, through `cargo metadata` |
+| `go`      | `@wtf/release-go`    | `@wtf/semantic-release-go`    | each `go.mod` that git tracks                             |
+| `maven`   | `@wtf/release-maven` | `@wtf/semantic-release-maven` | each `pom.xml` that git tracks                            |
+
+## Name the ecosystems in your config
+
+List the repo's ecosystems in `ecosystems` at the root of your config, beside `trains`. The list is
+required. Name each ecosystem by its module, whose default export is the ecosystem. A repo with two
+kinds of package names both.
+
+Each plugin exports its ecosystem at `./ecosystem`, such as `'@wtf/semantic-release-npm/ecosystem'`.
+So you only need to name the plugin you install. The ecosystem's own package, such as
+`'@wtf/release-npm'`, is the same ecosystem, for a repo that installs that package. With a global
+install of semantic-release, such as the one the to-be-continuous semantic-release component makes,
+only the plugin's export works: the plugin keeps the ecosystem's package in its own `node_modules`.
 
 ```js norun
 // release.config.mjs
@@ -32,36 +47,156 @@ 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/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`.
-
-## What the trains make of the packages
-
-- **Membership.** A package is of the train whose `paths` hold its folder (`dir`). A folder the
-  paths of two trains hold fails with `ETRAINOVERLAP`.
-- **Order.** A train depends on another when a package of its depends on a package of the other's
-  by a `runtime`, `peer` or `build` dependency; `dev` makes no edge. The trains release in the order
-  of those edges and of `dependsOn` ([Dependency rules](dependency-rules.md)).
-- **Checks.** A package that publishes, of a dependency that reaches the registry (a `range` that is
-  not `undefined`), on a package that publishes, must depend on a package of a train
-  (`EDEPENDENCYNOTRAIN`) that has released (`EDEPENDENCYNORELEASE`), at a version a release of that
-  train has (`EDEPENDENCYUNSATISFIED`).
-- **Versions.** A release stamps each range on a package of another train of that train's last
-  release, of its tags that `HEAD` holds (`releasedVersions` of `@wtf/release-trains/packages`).
-- **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
-
-`@wtf/release-trains/ecosystem` declares it:
+The plugins load each ecosystem the way a `wrap` entry loads the plugin it wraps: by its name, by
+its path from the repo (`./release/mine.mjs`), or by its `file:` URL. The run fails with
+`EECOSYSTEM` when an ecosystem cannot be loaded, when its default export is not an ecosystem, or
+when it has the same name as another ecosystem.
+
+An ecosystem that finds no manifest of its kind in the repo gives no package. So naming one more
+ecosystem costs a repo nothing. For example, cargo's ecosystem gives no package in a repo without a
+`Cargo.toml` at its root, and does not run `cargo`.
+
+## What the trains do with the packages
+
+- **Membership.** A package belongs to the train whose `paths` hold its folder (`dir`). A folder
+  that the paths of two trains hold fails with `ETRAINOVERLAP`.
+- **Order.** A train depends on another train when one of its packages depends on one of the other
+  train's packages by a `runtime`, `peer` or `build` dependency. A `dev` dependency does not count.
+  The trains release in the order of these dependencies and of `dependsOn` (see
+  [Trains that depend on other trains](dependency-rules.md)).
+- **Checks.** Take a published package that depends on another published package by a range that
+  reaches the registry (a `range` that is not `undefined`). The package it depends on must belong to
+  a train (`EDEPENDENCYNOTRAIN`). That train must have released (`EDEPENDENCYNORELEASE`), and one
+  of its releases must be within the range (`EDEPENDENCYUNSATISFIED`).
+- **Versions.** A release stamps each range on another train's package with that train's last
+  release, read from the train's tags that `HEAD` holds (`releasedVersions` of
+  `@wtf/release-trains/packages`).
+- **Cascade.** When another train's last release falls outside a range that this train's last
+  release published, this train releases again. It releases a major when a major left a `peer`
+  range behind, and a patch for any other kind.
+- **Trains without the ecosystem's packages.** A publishing plugin (`@wtf/semantic-release-npm`,
+  `-cargo`, `-go`, `-maven`) does nothing in the run of a train that holds none of its ecosystem's
+  packages. It says so in the log and asks for no credential. So a config with several ecosystems
+  can list every plugin for every train, and a train that holds only npm packages skips the crates.
+
+## The built-in ecosystems
+
+Each built-in ecosystem reads its manifests from the working tree, or from a commit when the trains
+ask for one. The sections below show what each one counts as a package, how it maps dependencies to
+the kinds `runtime`, `peer`, `build` and `dev`, and how its `resolve` and `satisfies` work.
+
+### npm
+
+`@wtf/release-npm` reads each `package.json` that git tracks and that has a name. It reads a
+commit's files with `git show`.
+
+- **Published:** every package that is not `private`.
+- **Kinds:** `dependencies` and `optionalDependencies` are `runtime`, `peerDependencies` are `peer`,
+  and `devDependencies` are `dev`.
+- **Range:** the range the manifest lists, such as `workspace:^`. A devDependency has no range,
+  because no consumer installs it.
+- **`resolve`:** pnpm's rules for the workspace protocol. `workspace:^` with `7.0.0` gives
+  `^7.0.0`.
+- **`satisfies`:** semver's rules. A range that names no version, such as `*`, a tag or a path,
+  takes any version.
+
+See [Publish npm packages](publishing.md).
+
+### cargo
+
+`@wtf/release-cargo` reads the Cargo workspace at the root of the repo with
+`cargo metadata --no-deps --format-version 1`. For a commit, it exports the files with
+`git archive` into the system's temporary files, unpacks them with `tar`, reads them, and removes
+them.
+
+- **Published:** every crate without `publish = false`.
+- **Kinds:** a normal dependency is `runtime`, a build dependency is `build`, and a dev-dependency
+  is `dev`.
+- **Range:** the requirement that cargo reports, such as `^0.0.0-development`. A dev-dependency
+  without a version has no range, because cargo drops it when it packages the crate.
+- **`resolve`:** the version itself, as the stamp writes it (`runtime = "1.4.0"`).
+- **`satisfies`:** cargo's rules. The ecosystem rewrites the requirement as an npm range and checks
+  it with semver:
+
+| cargo         | semver       | takes                  |
+| ------------- | ------------ | ---------------------- |
+| `1.2.3`       | `^1.2.3`     | `>=1.2.3, <2.0.0`      |
+| `1.2`         | `^1.2`       | `>=1.2.0, <2.0.0`      |
+| `0.2.1`       | `^0.2.1`     | `>=0.2.1, <0.3.0`      |
+| `~1.2.3`      | `~1.2.3`     | `>=1.2.3, <1.3.0`      |
+| `=1.2.3`      | `=1.2.3`     | `1.2.3`                |
+| `>=1.2, <1.5` | `>=1.2 <1.5` | `>=1.2.0, <1.5.0`      |
+| `1.*`, `*`    | `1.*`, `*`   | `>=1.0.0, <2.0.0`; any |
+
+See [Publish Cargo crates](publishing-crates.md).
+
+### Go
+
+`@wtf/release-go` reads each `go.mod` that git tracks, except those under a `vendor` or `testdata`
+folder. It reads a commit's files with `git show`.
+
+- **Name:** the module path from the `module` line. A go.mod without one, or two go.mod files with
+  the same path, fail with `EGOMOD`.
+- **Published:** every module that Go can fetch, which means the first element of its path has a
+  dot (`example.com/repo/core`, not `tools`).
+- **Kinds:** each `require` of another module of the repo is `runtime`, Go's only kind. This holds
+  for a require on its own line or in a block, and for one marked `// indirect`.
+- **Range:** the version the require names, such as `v0.0.0`.
+- **`resolve`:** the version itself with a `v`, as the stamp writes it (`v1.4.0`).
+- **`satisfies`:** Go's minimal version selection. The version must have the same major and be the
+  same version or a later one. Prereleases follow semver's order.
+
+| 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 |
+
+See [Publish Go modules](publishing-go-modules.md).
+
+### Maven
+
+`@wtf/release-maven` reads each `pom.xml` that git tracks, except one in a `src` or a `target`
+folder. It reads a commit's files with `git show`, and parses them with a small XML reader of its
+own.
+
+- **Name:** `groupId:artifactId`. When the pom writes no groupId, the module takes its parent's.
+- **Published:** every module, unless `maven.deploy.skip` is `true` in its `<properties>` or in
+  those of a parent in the repo. The module's own value comes first.
+- **Kinds:**
+  - The `<parent>`, and each `<dependency>` with the scope `compile`, `runtime` or no scope, are
+    `runtime`.
+  - The scope `provided` is `peer`.
+  - The scope `test` is `dev`, with no range, because no consumer resolves it.
+  - The scope `system` is not a dependency.
+  - A `<dependencyManagement>` entry with the scope `import` is `runtime`.
+  - A build plugin, or a plugin's dependency, is `build`.
+- **Range:** the `<version>` as written, including `${project.version}`.
+- **`resolve`:** the version itself, as the stamp writes it. A range of the author's own stays as
+  it is.
+- **`satisfies`:** Maven's rules, in 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 never causes a cascade, and the release never rewrites a range of your own. See
+[Publish Maven modules](publishing-maven.md).
+
+## Write your own ecosystem
+
+Write an ecosystem when your repo holds a kind of package that none of the built-in ecosystems
+reads.
+
+### The interface
+
+`@wtf/release-trains/ecosystem` declares the interface:
 
 ```ts fragment
 export interface Ecosystem {
@@ -90,15 +225,16 @@ export interface Dependency {
 }
 ```
 
-`packages` is asked of the working tree (no `ref`), and of a commit, as the tag of a train's last
-release, which a cascade reads. It runs everything by the `system` of its context, as every library
-does ([The system](system.md)): files, git, and the tool of the ecosystem.
+The trains call `packages` for the working tree, with no `ref`. They also call it for a commit, such
+as the tag of a train's last release, which a cascade reads. `packages` does everything through its
+context's `system`, as every library does: files, git, and the ecosystem's own tool. See
+[The system](system.md).
 
-## Writing one
+### An example
 
-An ecosystem is a module whose default export is an `Ecosystem`. Here is one of a manifest of its
-own, `release.json` of each folder, of a name, a flag of whether it publishes, and its dependencies
-of exact versions:
+An ecosystem is a module whose default export is an `Ecosystem`. The example below reads a manifest
+of its own, a `release.json` in each folder. The manifest holds a name, a flag that says whether the
+package publishes, and dependencies at exact versions:
 
 ```ts
 import { git, gitOf, trackedFiles } from '@wtf/release-system/git'
@@ -156,100 +292,30 @@ const ecosystem: Ecosystem = {
 export default ecosystem
 ```
 
-What to get right:
-
-- **`range` is what a release publishes.** `undefined` of a dependency nothing of reaches the
-  registry, as a dev-dependency a release drops: it is then checked of nothing and cascades nothing.
-- **`resolve` is the stamp.** It says the range a release writes of a dependency, of the version the
-  trains give it, as the ecosystem's own publish writes it; the cascade compares what the last
-  release published and what the next would, so the two must agree. A range of the author's own,
-  which names its versions itself, is itself: a release is no fix of it.
-- **`satisfies` is the ecosystem's rules.** A prerelease within its bounds too, as `1.5.0-beta.1` of
-  `^1.4.0`: the trains release prereleases on their channels.
-- **No manifest is no package.** A repo of none of the ecosystem's manifests gives `[]`, of no
-  failure, so a config can name it before the first manifest is there.
-- **The system, always.** No `node:*`, no `process`, no global `fetch`: what the module does outside
-  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`, `@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.
-
-### npm
-
-`@wtf/release-npm` reads each `package.json` git tracks, of the working tree or of a commit by
-`git show`, of a name. A package is published unless it is `private`. `dependencies` and
-`optionalDependencies` are `runtime`, `peerDependencies` `peer`, `devDependencies` `dev`, each of
-the range it lists, as `workspace:^`; a devDependency is of no range, as no consumer installs it.
-`resolve` is pnpm's rules of the workspace protocol (`workspace:^` and `7.0.0` is `^7.0.0`), and
-`satisfies` is semver's, a range that names no version, as `*`, a tag or a path, taking any. See
-[Publishing](publishing.md).
-
-### cargo
-
-`@wtf/release-cargo` reads the Cargo workspace at the root of the repo by
-`cargo metadata --no-deps --format-version 1`, of the working tree, or of a commit, which it exports
-by `git archive` into the system's temporary files, unpacks by `tar`, reads and removes. A crate is
-published unless `publish = false`. A normal dependency is `runtime`, a build one `build`, a dev one
-`dev`, each of the requirement cargo reads, as `^0.0.0-development`; a dev-dependency of no version
-is of no range, as cargo drops it as it packages. `resolve` is the version itself, as the stamp
-writes it (`runtime = "1.4.0"`), and `satisfies` is cargo's rules, by semver, once the requirement
-is written as npm writes a range:
-
-| cargo         | semver       | takes                  |
-| ------------- | ------------ | ---------------------- |
-| `1.2.3`       | `^1.2.3`     | `>=1.2.3, <2.0.0`      |
-| `1.2`         | `^1.2`       | `>=1.2.0, <2.0.0`      |
-| `0.2.1`       | `^0.2.1`     | `>=0.2.1, <0.3.0`      |
-| `~1.2.3`      | `~1.2.3`     | `>=1.2.3, <1.3.0`      |
-| `=1.2.3`      | `=1.2.3`     | `1.2.3`                |
-| `>=1.2, <1.5` | `>=1.2 <1.5` | `>=1.2.0, <1.5.0`      |
-| `1.*`, `*`    | `1.*`, `*`   | `>=1.0.0, <2.0.0`; any |
-
-See [Publishing crates](publishing-crates.md).
-
-### Go
-
-`@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.
-
-| 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 |
-
-See [Publishing Go modules](publishing-go-modules.md).
-
-### Maven
-
-`@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).
+### What to get right
+
+- **`range` is what a release publishes.** Use `undefined` for a dependency that never reaches the
+  registry, such as a dev-dependency that a release drops. The trains then check nothing for it, and
+  it causes no cascade.
+- **`resolve` is the stamp.** It returns the range that a release writes for a dependency, given
+  the version the trains pass in, the way the ecosystem's own publish writes it. The cascade
+  compares what the last release published with what the next release would publish, so the two
+  must agree. A range of the author's own that names its versions itself stays as it is: a release
+  does not fix it.
+- **`satisfies` follows the ecosystem's rules.** It must accept a prerelease within the bounds too,
+  such as `1.5.0-beta.1` for `^1.4.0`, because the trains release prereleases on their channels.
+- **No manifest means no package.** In a repo without any of the ecosystem's manifests, return `[]`
+  rather than fail. A config can then name the ecosystem before the first manifest exists.
+- **Always use the system.** Do not use `node:*`, `process` or the global `fetch`. Everything the
+  module does outside itself goes through `context.system`. The trains can then run it on a CLI's
+  system, or on a test's system in memory.
+
+### Publish the packages
+
+The ecosystem does not publish. Write a semantic-release plugin for that, as
+`@wtf/semantic-release-npm`, `@wtf/semantic-release-cargo`, `@wtf/semantic-release-go` and
+`@wtf/semantic-release-maven` are. The plugin:
+
+- reads `trains`, `ecosystems` and `train` from the root of the config;
+- finds its train's packages with `ownersOf` from `@wtf/release-trains/packages`;
+- reads the other trains' versions with `releasedVersions`, which throws the trains' errors.