@wtf/release-docs 8.2.1 → 8.2.3

package/guides/getting-started.md

@@ -1,22 +1,64 @@
 # Getting started
 
-The release trains release several trains from one monorepo with semantic-release alone: no other
-tool, and no CLI of their own. A **train** is a set of folders that is released together. It has its
-own tags, its own version, its own release notes and its own changelog. A commit counts for each
-train whose files it changes, and for no other train.
-
-There are two layers:
-
-- **The libraries**, of no release tool: `@wtf/release-system` (the system, paths, git, validators
-  of options and `ReleaseError`, of no train, the base of the others), `@wtf/release-trains` (the
-  trains, their commits, their checks, the folders a build generates), `@wtf/release-npm`
-  (every package of a train published), `@wtf/release-replace` (text replaced in files, as the
-  version of a badge) and `@wtf/release-validate` (a config validated by any Standard Schema). Each
-  function takes the `system` it runs by: see [The system](system.md).
-- **The plugins of semantic-release**, each a thin adapter over its library:
-  `@wtf/semantic-release-trains` (the trains checked, a plugin given the train's commits alone, and
-  the folders a build generates staged), `@wtf/semantic-release-npm` and
-  `@wtf/semantic-release-replace`.
+wtf release lets one semantic-release setup release several parts of a monorepo, each with its own
+version. You do not need another tool or a CLI. This page explains the few ideas you need. Then it
+walks you through a config, a first run and a first release.
+
+## What a train is
+
+A **train** is a set of folders that you release together. Each train has its own tags, its own
+version, its own release notes and its own changelog.
+
+A commit counts for each train whose files it changes, and for no other train. So a breaking change
+in one train makes a major release of that train only. The other trains keep their versions.
+
+You run semantic-release once for each train. When one train depends on another, you release the
+other train first.
+
+## Which packages it releases
+
+An **ecosystem** tells the trains how to read one kind of package: where its manifests are, what it
+depends on, and what a version range means. Four ecosystems are built in, and one repo can mix them:
+
+| Ecosystem | Manifests                       | Plugin                        | Guide                                          |
+| --------- | ------------------------------- | ----------------------------- | ---------------------------------------------- |
+| npm       | each `package.json`             | `@wtf/semantic-release-npm`   | [Publish npm packages](publishing.md)          |
+| Cargo     | the Cargo workspace at the root | `@wtf/semantic-release-cargo` | [Publish Cargo crates](publishing-crates.md)   |
+| Go        | each `go.mod`                   | `@wtf/semantic-release-go`    | [Publish Go modules](publishing-go-modules.md) |
+| Maven     | each `pom.xml`                  | `@wtf/semantic-release-maven` | [Publish Maven modules](publishing-maven.md)   |
+
+You can also write an ecosystem of your own for any other kind of package. See
+[How ecosystems work](ecosystems.md).
+
+## Libraries and plugins
+
+wtf release has two layers:
+
+- **Libraries** do the work. They do not depend on semantic-release or on any other release tool.
+  Each function takes the `system` it runs on from its caller, so you can also run the libraries
+  from a CLI or a script of your own. See [The system](system.md).
+- **Plugins** let semantic-release run the libraries. Each plugin is a thin adapter over its
+  library.
+
+The libraries:
+
+- `@wtf/release-system` is the base of the other libraries: the system, paths and globs, git,
+  option validators and `ReleaseError`. It knows nothing about trains.
+- `@wtf/release-trains` handles the trains: their commits, their checks, and the folders a build
+  generates.
+- `@wtf/release-npm`, `@wtf/release-cargo`, `@wtf/release-go` and `@wtf/release-maven` are the
+  four ecosystems. Each one also publishes the train's packages of its kind.
+- `@wtf/release-replace` replaces text in files, such as the version in a badge.
+- `@wtf/release-validate` validates a config with any Standard Schema.
+
+The plugins:
+
+- `@wtf/semantic-release-trains` checks the trains, gives a plugin it wraps only the train's
+  commits, and stages the folders a build generates.
+- `@wtf/semantic-release-npm`, `@wtf/semantic-release-cargo`, `@wtf/semantic-release-go` and
+  `@wtf/semantic-release-maven` publish the train's packages of one ecosystem.
+- `@wtf/semantic-release-replace` replaces text in files during a release.
+- `@wtf/semantic-release-validate` validates the config of a run with a schema of your own.
 
 ## Install
 
@@ -28,31 +70,52 @@ pnpm add --save-dev semantic-release @wtf/semantic-release-trains \
   @semantic-release/changelog @semantic-release/git
 ```
 
-Each plugin is a package of its own, which semantic-release loads by its name, as the repo installs
-it. `@wtf/semantic-release-trains` is one, which a config lists once for each role: of `wrap`, it
-gives the plugin it wraps, as the analyzer and the notes generator, the train's commits alone; of
-`generated`, it stages the folders a build generates; and every entry checks the trains. Install
-each other the config names: `@wtf/semantic-release-npm`, `@wtf/semantic-release-replace`. semantic-release brings
-`@semantic-release/commit-analyzer` and `@semantic-release/release-notes-generator` with it, which
-an entry of `wrap` loads as semantic-release does.
+Each plugin is a package of its own. semantic-release loads it by name, from the packages your repo
+installs.
+
+You list `@wtf/semantic-release-trains` once for each role it plays:
+
+- With `wrap`, it gives the plugin it wraps, such as the commit analyzer or the release notes
+  generator, only the train's commits.
+- With `generated`, it stages the folders a build generates.
+- Every entry also checks the trains.
+
+Install each other plugin that your config names, such as `@wtf/semantic-release-npm` or
+`@wtf/semantic-release-replace`. semantic-release already brings
+`@semantic-release/commit-analyzer` and `@semantic-release/release-notes-generator` with it. A
+`wrap` entry loads them the same way semantic-release does.
 
 ## Write the config
 
-`release.config.mjs` is an ordinary config of semantic-release, and yours: which plugins run, with
-which options, and in which order. Declare the trains once, at its root: semantic-release gives each
-option of the root to every plugin, so each plugin of the trains reads `trains` from there. The train
-of a run is `RELEASE_TRAIN` of its environment, which each plugin reads, as a plugin of
-semantic-release reads a variable of its own. `@wtf/semantic-release-trains/config` gives values to
-write the config with, and adds no plugin.
-
-The examples of the guides are the trains this repo releases its packages in: `system`
-(`packages/release-system`), `trains` (`packages/release-trains`, `packages/semantic-release-trains`,
-…), `replace` (`packages/release-replace`, `packages/semantic-release-replace`), `validate`
-(`packages/release-validate`, `packages/semantic-release-validate`) and `docs` (`packages/docs`).
+`release.config.mjs` is an ordinary semantic-release config, and you own it. You choose the
+plugins, their options and their order.
+
+Declare the trains once, at the root of the config. semantic-release passes every root option to
+every plugin, so each trains plugin reads `trains` from there.
+
+Each run releases one train. Each plugin reads the name of that train from the `RELEASE_TRAIN`
+variable in the run's environment, the same way any semantic-release plugin reads a variable of its
+own.
+
+`@wtf/semantic-release-trains/config` exports values that help you write the config. It does not
+add any plugin.
+
+The examples in these guides use the trains that this repo releases its own packages in:
+
+| Train      | Folders                                                           |
+| ---------- | ----------------------------------------------------------------- |
+| `system`   | `packages/release-system`                                         |
+| `trains`   | `packages/release-trains`, `packages/semantic-release-trains`, …  |
+| `replace`  | `packages/release-replace`, `packages/semantic-release-replace`   |
+| `validate` | `packages/release-validate`, `packages/semantic-release-validate` |
+| `docs`     | `packages/docs`                                                   |
+
 `@wtf/release-trains` and `@wtf/release-replace` list `@wtf/release-system`, so `trains` and
-`replace` depend on `system`; `validate` depends on none; and the docs package lists every package,
-so `docs` releases last. A guide's example shows the trains it needs; the repo's own
-`release.config.mjs` declares them all, each tagged `<train>-v<version>`.
+`replace` depend on `system`. `validate` depends on no other train. The docs package lists every
+package, so `docs` releases last.
+
+Each example shows only the trains it needs. The repo's own `release.config.mjs` declares them all,
+and tags each one `<train>-v<version>`. Here is a config with two trains:
 
 ```js train=trains
 // release.config.mjs
@@ -99,15 +162,16 @@ export default {
 }
 ```
 
-The same config can be of literals, which imports nothing, as a global install of semantic-release
-reads one, as the semantic-release component of to-be-continuous does; or JSON, as
-`.releaserc.json`: each entry is JSON already, and the tag format of the train is written out, or
-given on the command line: see
-[Configuring trains](configuring-trains.md#a-config-of-literals).
+You can also write the same config with literals only, so that it imports nothing. A global
+install of semantic-release can read such a config, as the semantic-release component of
+to-be-continuous does. Or write it as JSON, in `.releaserc.json`. Each entry is JSON already, and
+you either write out the train's tag format or pass it on the command line. See
+[A config of literals](configuring-trains.md#a-config-of-literals).
 
-A file at the root of the repo, such as the lockfile, counts for no train. List it in the `shared`
-of each train that must release when it changes alone: beside the files of a train, it counts for
-that train only. See [Configuring trains](configuring-trains.md#which-commits-count).
+A file at the root of the repo, such as the lockfile, counts for no train. If a train must release
+when only that file changes, list the file in the train's `shared`. When a commit changes the file
+together with the files of a train, the commit counts for that train only. See
+[Which commits count](configuring-trains.md#which-commits-count).
 
 ## Run one train
 
@@ -125,39 +189,41 @@ releases nothing:
 RELEASE_TRAIN=trains npx semantic-release --dry-run --no-ci
 ```
 
-Release a train that another train depends on first, as `system` before `trains`. The plugin warns
-about a dependency with commits that are not released. See [Dependency rules](dependency-rules.md).
+Release a train that another train depends on first, such as `system` before `trains`. The plugin
+warns you when a dependency train has commits that it has not released. See
+[Trains that depend on other trains](dependency-rules.md).
 
-## The version is the tag's
+## Where the version lives
 
-No release writes a version into git. The tag is the version, and each `package.json` keeps a
-placeholder, as `0.0.0-development`. The publish plugin gives each package the version of the
-release in the copy it packs: see [Publishing](publishing.md).
+No release writes a version into git. The tag is the version. Each `package.json` keeps a
+placeholder, such as `0.0.0-development`. The publish plugin writes the release's version into the
+copy of each package that it packs. See [Publish npm packages](publishing.md).
 
-## More than tags and a changelog
+## Do more than tags and a changelog
 
-- [Publishing](publishing.md): every package of the train published, in the order of their
-  dependencies, by npm, pnpm or a publisher of your own.
-- [Changelogs](changelogs.md): a changelog of each package of the train.
-- [Generated folders](configuring-trains.md#generated-folders): an API reference a build writes,
-  committed with the release, a file it no longer writes deleted.
-- `@semantic-release/gitlab` or `@semantic-release/github`, listed last: the release of the tag of the
-  train.
-- [The system](system.md): the libraries on a system of your own.
+- [Publish npm packages](publishing.md): publish every package in the train in dependency order,
+  with npm, pnpm or a publisher of your own.
+- [Changelogs](changelogs.md): write a changelog for each package in the train.
+- [Generated folders](configuring-trains.md#generated-folders): commit a folder that a build
+  writes, such as an API reference, with the release. A file that the build no longer writes is
+  deleted.
+- `@semantic-release/gitlab` or `@semantic-release/github`, listed last: create the release of the
+  train's tag on your host.
+- [The system](system.md): run the libraries on a system of your own.
 
-## The first release
+## Make the first release
 
-A train with no tag yet gets the first version of semantic-release, `1.0.0`. The run says so. To
-start a train from a version that it already has, tag that commit first, with the tag format of the
-train, and push the tag:
+A train with no tag yet gets semantic-release's first version, `1.0.0`, and the run says so. To
+start a train from a version that it already has, tag that commit first with the train's tag
+format, and push the tag:
 
 ```sh
 git tag trains-v2.1.0 <commit>
 git push origin trains-v2.1.0
 ```
 
-## In CI
+## Release in CI
 
-Build before the release, in a job of its own, and run the trains one after another, in the order of
-their dependencies: runs of one job, or jobs of a matrix that cannot run at the same time. See
-[CI recipes](ci-recipes.md).
+Build before the release, in a job of its own. Then run the trains one after another, in dependency
+order. You can run them all in one job, or as jobs of a matrix that cannot run at the same time.
+See [Run releases in CI](ci-recipes.md).