@wtf/release-docs 8.2.0 → 8.2.2

package/guides/publishing-go-modules.md

@@ -1,23 +1,29 @@
-# Publishing Go modules
+# Publish Go modules
 
-A release train can release the Go modules of a repo beside its npm packages and crates: one
-version, one train tag, and a retry that finishes what stopped. Go has no registry to upload to. A
-version of a module is a git tag of its repo, `<folder>/v<version>`, or `v<version>` for a module at
-the root, and the Go proxy reads the module from that tag. The library is
-[`@wtf/release-go`](../../release-go/README.md), and the plugin over it
-[`@wtf/semantic-release-go`](../../semantic-release-go/README.md).
+[`@wtf/semantic-release-go`](../../semantic-release-go/README.md) releases the Go modules of a repo
+that belong to a train. Use it when a train holds Go modules, alone or beside npm packages and
+crates in the same release. They share one version and one train tag, and a retry finishes a
+release that stopped.
 
-`@wtf/release-go` is the ecosystem of Go too, its default export, which the plugin exports at
-`./ecosystem` and a config names in `ecosystems` as `'@wtf/semantic-release-go/ecosystem'`. The
-trains then read the modules of the repo as they read npm packages ([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.
+Go has no registry to upload to. A module's version is a git tag in its repo: `<folder>/v<version>`,
+or `v<version>` for a module at the root. The Go proxy reads the module from that tag. So the plugin
+publishes a module by pushing its tag.
 
-## The model
+The plugin runs on the library [`@wtf/release-go`](../../release-go/README.md). The library's
+default export is the Go ecosystem, and the plugin exports the same ecosystem at `./ecosystem`. Add
+`'@wtf/semantic-release-go/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 train tag is the version, and no version is written into git on the branch. Each go.mod that
-requires another module of the repo requires it at a placeholder, `v0.0.0`, and builds against the
-module in the repo by a `go.work` or a `replace` (see [go.work or replace](#gowork-or-replace)):
+## Turn it on
+
+### Require the repo's modules at a placeholder
+
+The train tag holds the version, and git on the branch holds no version. Each go.mod that requires
+another module of the repo requires it at a placeholder, `v0.0.0`. It builds against the module in
+the repo through a `go.work` or a `replace` (see
+[Build against the repo's modules](#build-against-the-repos-modules-gowork-or-replace)):
 
 ```text
 module example.com/repo/cli
@@ -27,13 +33,18 @@ go 1.24
 require example.com/repo/core v0.0.0
 ```
 
-A module is each go.mod git tracks, but those under a `vendor` or `testdata` folder, which Go
-ignores. It is of the train whose `paths` hold its folder; the plugin reads `trains`, `ecosystems`
-and `train` of the root of the config, as `@wtf/semantic-release-npm` does. A module of no train is
-tagged by no release. A module whose path has no dot in its first element, as `module tools`, cannot
-be fetched by Go, so no release tags it, and a module that requires it fails before the tag
-(`EGOPRIVATE`). `ecosystems` must list the ecosystem of Go, or the plugin fails in
-`verifyConditions` with `EGOECOSYSTEM`:
+### Add the Go ecosystem
+
+A module is each go.mod that git tracks, except those under a `vendor` or `testdata` folder, which
+Go ignores. A module belongs to the train whose `paths` hold its folder. The plugin reads `trains`,
+`ecosystems` and `train` from the root of the config, as `@wtf/semantic-release-npm` does. No
+release tags a module that belongs to no train.
+
+Go cannot fetch a module whose path has no dot in its first element, such as `module tools`. So no
+release tags such a module, and a module that requires it fails before the tag (`EGOPRIVATE`).
+
+`ecosystems` must list the Go ecosystem. Otherwise the plugin fails in `verifyConditions` with
+`EGOECOSYSTEM`:
 
 ```js norun
 // release.config.mjs
@@ -43,27 +54,10 @@ export const ecosystems = [
 ]
 ```
 
-## The commit the tags name
-
-Go reads a module's go.mod at the commit its tag names, and uses the requires it finds there. The
-release commit of the branch still has the placeholders, so tagging it would publish
-`require example.com/repo/core v0.0.0`, a version that does not exist.
-
-So the run of the tag writes the versions into the go.mod files (`prepare`), then makes a commit of
-those files on top of the release commit, on no branch, and tags that commit with each module's tag
-(`publish`). The branch, the index and the working tree are left as they are; only the tags reach
-the remote. The commit is `chore(release): Go modules of <train> <version>`, of the author in
-`GIT_AUTHOR_NAME` and `GIT_AUTHOR_EMAIL` (and the committer in `GIT_COMMITTER_*`), else
-`semantic-release-bot`. When no go.mod changed, as for modules that require no other module of the
-repo, the release commit itself is tagged.
+### List the plugin in the tag's run
 
-The tag of a module in a folder of its major, as `example.com/repo/lib/v2` in `lib/v2`, is the folder
-above with the version, `lib/v2.0.0`, as Go looks it up.
-
-## Run it on the tag
-
-The branch run decides the version and pushes the train tag, as for any train. The run of the tag
-lists the plugin:
+The branch run decides the version and pushes the train tag, as for any train. List the plugin in
+the tag's run:
 
 ```js norun
 // release.config.mjs
@@ -76,14 +70,16 @@ export const tagPlugins = [
 ]
 ```
 
-The plugin pushes its tags to the `repositoryUrl` of the run, which in a CI job holds the token
-semantic-release pushes by, so the job needs nothing more than the branch run does: `git`, and a
-token that may create the module tags. Where the tags of the repo are protected by a pattern that
-matches the module tags too, the token's role must be allowed to create them. The job needs no
-`go`, unless `proxy` is on.
+### What the jobs need
 
-The module tags start pipelines of their own. Let a workflow rule run a pipeline for the train
-tags alone, and none for any other tag:
+The plugin pushes its tags to the run's `repositoryUrl`. In a CI job, that URL holds the token that
+semantic-release pushes with. So the job needs nothing more than the branch run does: `git`, and a
+token that may create the module tags. If the repo protects tags with a pattern that also matches
+the module tags, the token's role must be allowed to create them. The job needs no `go`, unless
+`proxy` is on (see [Ask the Go proxy](#ask-the-go-proxy)).
+
+The module tags start pipelines of their own. Add a workflow rule that runs a pipeline for the train
+tags only, and none for any other tag:
 
 ```yaml
 workflow:
@@ -96,10 +92,49 @@ workflow:
     - if: $CI_COMMIT_BRANCH
 ```
 
-## Modules of several trains
+## What a release does
+
+1. **`verifyConditions`** checks the options and reads the go.mod files that git tracks. It selects
+   the modules that the release tags, and reads each other train's last release from its tags. A
+   repo that cannot be released fails here, before the tag (see
+   [When modules depend on other trains](#when-modules-depend-on-other-trains)).
+2. **`verifyRelease`** checks each module's path against the major of the release's version
+   (`EGOMAJOR`; see [Release a new major](#release-a-new-major)).
+3. **`prepare`** checks the majors again and writes the versions into the go.mod files. It writes
+   the release's version into each require of a module of the train, and each other train's last
+   release into each require of that train's modules, in every go.mod of the repo. Then it reads the
+   files again, and a require that is not at its train's version fails the run (`EGOVERSION`; see
+   [What the release changes in go.mod](#what-the-release-changes-in-gomod)).
+4. **`publish`** commits the changed go.mod files and tags that commit with each module's tag (see
+   [Tag a commit that holds the versions](#tag-a-commit-that-holds-the-versions)). It skips each tag
+   the remote already has. With `proxy`, it then asks the Go proxy for each module.
+
+A dry run of semantic-release runs only `verifyConditions` and `verifyRelease`. It writes no version
+and creates no tag.
+
+### Tag a commit that holds the versions
+
+Go reads a module's go.mod at the commit that its tag names, and uses the requires it finds there.
+The release commit on the branch still has the placeholders. Tagging it would publish
+`require example.com/repo/core v0.0.0`, a version that does not exist.
+
+So the tag's run writes the versions into the go.mod files in `prepare`. In `publish`, it commits
+those files on top of the release commit, on no branch, and tags that commit with each module's
+tag. The branch, the index and the working tree stay as they are; only the tags reach the remote.
+
+- The commit message is `chore(release): Go modules of <train> <version>`.
+- The author comes from `GIT_AUTHOR_NAME` and `GIT_AUTHOR_EMAIL`, and the committer from
+  `GIT_COMMITTER_*`. Without them, both are `semantic-release-bot`.
+- When no go.mod changed, as for modules that require no other module of the repo, the plugin tags
+  the release commit itself.
+
+A module can live in a folder named after its major, such as `example.com/repo/lib/v2` in `lib/v2`.
+Its tag is the folder above with the version, `lib/v2.0.0`, because that is where Go looks it up.
 
-A repo can release its modules in several trains, each with its own version and tags: a core, and a
-CLI that requires it.
+## When modules depend on other trains
+
+A repo can release its modules in several trains, each with its own version and tags. For example,
+a core and a CLI that requires it:
 
 ```js norun
 // release.config.mjs
@@ -109,46 +144,62 @@ export const trains = {
 }
 ```
 
-The trains read the requires by the ecosystem of Go, so a train whose modules require another
-train's modules releases after it, as an npm package of one train that depends on a package of
-another does; no `dependsOn` says so.
+The trains read the requires through the Go ecosystem. A train whose modules require another
+train's modules 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`.
+
+### What versions the release writes
+
+A train's release writes its own version into each require of its modules. For each other train,
+it writes the last release whose tag the tagged commit holds, into each require of that train's
+modules, in every go.mod of the repo. For example, the release `cli-v1.0.0` comes after
+`core-v1.4.0`. It tags `cli/v1.0.0` on a commit whose `cli/go.mod` has
+`require example.com/repo/core v1.4.0`. It tags nothing for core: the release of core made
+`core/v1.4.0`.
+
+### Checks before the tag
 
-The release of a train writes its own version into each require of its modules, and the last
-release of each other train, of its tags that the tag's commit holds, into each require of that
-train's modules, in every go.mod of the repo. So the release `cli-v1.0.0`, after `core-v1.4.0`,
-tags `cli/v1.0.0` on a commit whose `cli/go.mod` has `require example.com/repo/core v1.4.0`, and
-tags nothing of core, whose `core/v1.4.0` the release of core made.
+The trains run these checks before the tag:
 
-The checks are the trains', before the tag: a module of the release that requires a module of no
-train fails with `EDEPENDENCYNOTRAIN`, and of a train that has no release with
-`EDEPENDENCYNORELEASE`, as neither has a version Go could fetch; a module the paths of two trains
-hold fails with `ETRAINOVERLAP`.
+- A module of the release that requires a module of no train fails with `EDEPENDENCYNOTRAIN`.
+- A module of the release that requires a module of a train with no release fails with
+  `EDEPENDENCYNORELEASE`.
+- A module that the paths of two trains hold fails with `ETRAINOVERLAP`.
 
-Go's minimal version selection takes the version a module requires or a later one of the same
-major, so `require example.com/repo/core v1.4.0` takes core 1.5.0, and a release of core owes cli
-nothing ([Dependency rules](dependency-rules.md)). Core 2.0.0 is a module of another path (see
-[Majors](#majors)): cli takes it by changing its imports and its require, a change of cli's own,
-which releases cli.
+In the first two cases there is no version that Go could fetch.
 
-## Majors
+### When another train's release leaves a module behind
+
+Go's minimal version selection takes the required version or a later one of the same major. So
+`require example.com/repo/core v1.4.0` takes core 1.5.0, and a release of core owes cli nothing (see
+[Trains that depend on other trains](dependency-rules.md)). Core 2.0.0 is a module with another
+path (see [Release a new major](#release-a-new-major)). cli takes it by changing its imports and its
+require. That is a change in cli itself, so it releases cli.
+
+## Release a new major
 
 From v2 on, Go holds the major in the module path: `example.com/repo/core/v2`. A path that ends in
-`/vN` needs a release of major N, and a release of major 2 or more needs a path that ends in its
-major. The plugin checks this in `verifyRelease`, once semantic-release knows the version, and again
-in `prepare`, so a breaking change of a module whose path has no `/v2` fails before anything is
-tagged (`EGOMAJOR`). The error names the go.mod to change: write `module example.com/repo/core/v2`
-there, and change each import and each require of the module to the new path, in the commit of the
-breaking change. A `gopkg.in/` path carries its major in its own way and is not checked.
+`/vN` needs a release of major N. A release of major 2 or higher needs a path that ends in its
+major.
+
+The plugin checks this in `verifyRelease`, once semantic-release knows the version, and again in
+`prepare`. So a breaking change to a module whose path has no `/v2` fails before anything is tagged
+(`EGOMAJOR`). The error names the go.mod to change. In the commit of the breaking change:
 
-The module can stay in its folder (`core/go.mod`, tags `core/v2.0.0`), or move to a folder of its
-major (`core/v2/go.mod`, tags `core/v2.0.0` as well).
+1. Write `module example.com/repo/core/v2` in that go.mod.
+2. Change each import and each require of the module to the new path.
 
-## go.work or replace
+The plugin does not check a `gopkg.in/` path, which carries its major in its own way.
 
-Before a release, each go.mod requires the modules of the repo at `v0.0.0`, which does not exist, so
-the build must find them in the repo. Two ways:
+The module can stay in its folder (`core/go.mod`, tags `core/v2.0.0`). It can also move to a folder
+named after its major (`core/v2/go.mod`, tags `core/v2.0.0` as well).
 
-- **go.work**, at the root, which lists the modules of the repo and is no part of any module:
+## Build against the repo's modules: go.work or replace
+
+Before a release, each go.mod requires the repo's modules at `v0.0.0`, which does not exist. So the
+build must find them in the repo. There are two ways:
+
+- **go.work** at the root lists the repo's modules and is not part of any module:
 
   ```text
   go 1.24
@@ -159,8 +210,8 @@ the build must find them in the repo. Two ways:
   )
   ```
 
-  A build in the repo uses the modules of the workspace; a user's `go install` of a module reads its
-  go.mod alone, and never the repo's go.work.
+  A build in the repo uses the workspace's modules. A user's `go install` of a module reads only its
+  go.mod, never the repo's go.work.
 
 - **replace**, in each go.mod that requires a module of the repo:
 
@@ -170,39 +221,48 @@ the build must find them in the repo. Two ways:
   replace example.com/repo/core v0.0.0 => ../core
   ```
 
-  The release writes the version on the left of the replace too
-  (`replace example.com/repo/core v1.4.0 => ../core`), so it still applies to the version the
-  require names. But `go install example.com/repo/cli@v1.0.0` refuses a module whose go.mod has a
-  replace directive, so prefer go.work for a module people install by `go install`.
+  The release also writes the version on the left side of the replace
+  (`replace example.com/repo/core v1.4.0 => ../core`), so the replace still applies to the version
+  that the require names. But `go install example.com/repo/cli@v1.0.0` refuses a module whose go.mod
+  has a replace directive. Prefer go.work for a module that people install with `go install`.
+
+### What the release changes in go.mod
+
+The release changes only the version in each require of a repo module, and in each replace of one
+that names a version. It changes them in place, so comments, layout and line endings stay.
 
-A release changes only the version of each require of a module of the repo, and of each replace of
-one that names a version, where they stand: comments, layout and line endings stay. It does not
-touch go.sum and does not run `go mod tidy`. A go.sum needs no line for a module the build finds in
-the repo, by go.work or by a replace; and Go checks the modules a user fetches against its checksum
-database, not against the go.sum of the module that requires them. A require of a form the stamp
-does not read fails the run after it (`EGOVERSION`), so no go.mod is tagged at the wrong version.
+- It does not touch go.sum and does not run `go mod tidy`. A go.sum needs no line for a module that
+  the build finds in the repo, through go.work or a replace. Go checks the modules that a user
+  fetches against its checksum database, not against the go.sum of the module that requires them.
+- A require in a form that the stamp does not read fails the run after the stamp (`EGOVERSION`). So
+  no go.mod is tagged at the wrong version.
 
-## The proxy
+## Ask the Go proxy
 
-`proxy: true` asks the Go proxy for each module once its tag is pushed, by
-`go list -m -json <path>@v<version>`, with `GOWORK=off`, `GOFLAGS=-mod=mod` and the `GOPROXY` of
-the job, Go's own by default. The proxy then has the version, and pkg.go.dev lists it; the release
-links to the first module there. It is off by default: the public proxy cannot fetch a private repo.
-Turn it on for a public repo, in a job that has `go`:
+With `proxy: true`, the plugin asks the Go proxy for each module once its tag is pushed. It runs
+`go list -m -json <path>@v<version>` with `GOWORK=off`, `GOFLAGS=-mod=mod` and the job's `GOPROXY`,
+which is Go's own proxy by default. The proxy then has the version, and pkg.go.dev lists it. The
+release links to the first module there.
+
+`proxy` is off by default, because the public proxy cannot fetch a private repo. Turn it on for a
+public repo, in a job that has `go`:
 
 ```js norun
 // release.config.mjs
 export const go = ['@wtf/semantic-release-go', { proxy: true }]
 ```
 
-A proxy that does not give a module fails the run with `EGOPROXY`, as when it lags a new tag; a
-retry of the job of the tag skips the tags the remote has and asks again. Users of a private repo
-set `GOPRIVATE` to its path, and fetch it by git instead of the proxy.
+If the proxy does not return a module, as when it lags behind a new tag, the run fails with
+`EGOPROXY`. A retry of the tag's job skips the tags the remote has and asks again.
+
+Users of a private repo set `GOPRIVATE` to its path, and fetch it with git instead of the proxy.
+
+## When a publish fails
 
-## A release that stopped
+A tag on the remote stays. The checksum database records a module version the first time anyone
+fetches it, so a tag must never move.
 
-A tag the remote has stays: the checksum database records a module version the first time anyone
-fetches it, so a tag must never move. The plugin asks the remote for every tag before it makes
-anything, skips each it has, and pushes the rest in one atomic push, all or none. Retrying the job
-of the tag makes the tags that are missing. A remote that cannot be asked stops the run before
-anything is made (`EGOTAG`).
+Before it creates anything, the plugin asks the remote for every tag. It skips each tag the remote
+has, and pushes the rest in one atomic push: all of them or none. So retry the tag's job to create
+the missing tags. A remote that cannot be asked stops the run before anything is created
+(`EGOTAG`).