@wtf/release-docs 8.2.3 → 9.0.0

package/api/README.md

@@ -58,6 +58,8 @@
 - [@wtf/release-trains/errors](@wtf/release-trains/errors/README.md)
 - [@wtf/release-trains/generated](@wtf/release-trains/generated/README.md)
 - [@wtf/release-trains/git](@wtf/release-trains/git/README.md)
+- [@wtf/release-trains/gitlab](@wtf/release-trains/gitlab/README.md)
+- [@wtf/release-trains/links](@wtf/release-trains/links/README.md)
 - [@wtf/release-trains/packages](@wtf/release-trains/packages/README.md)
 - [@wtf/release-trains/paths](@wtf/release-trains/paths/README.md)
 - [@wtf/release-trains/schema](@wtf/release-trains/schema/README.md)

package/guides/ci-recipes.md

@@ -195,8 +195,8 @@ export default {
         ]
       : [
           ['@wtf/semantic-release-trains', { wrap: '@semantic-release/release-notes-generator' }],
-          ['@wtf/semantic-release-npm', { tarballDir: 'tarballs' }],
-          ['@semantic-release/gitlab', { assets: [{ path: 'tarballs/*.tgz', type: 'package' }] }]
+          '@wtf/semantic-release-npm',
+          ['@wtf/semantic-release-trains', { wrap: '@semantic-release/gitlab' }]
         ]
 }
 ```

package/guides/getting-started.md

@@ -209,6 +209,8 @@ copy of each package that it packs. See [Publish npm packages](publishing.md).
   deleted.
 - `@semantic-release/gitlab` or `@semantic-release/github`, listed last: create the release of the
   train's tag on your host.
+  Wrapped in the trains plugin, `@semantic-release/gitlab` links each package that the release
+  published. See [The links of the release](publishing.md#the-links-of-the-release).
 - [The system](system.md): run the libraries on a system of your own.
 
 ## Make the first release

package/guides/publishing-crates.md

@@ -60,8 +60,16 @@ export const tagPlugins = [
   ['@wtf/semantic-release-trains', { wrap: '@semantic-release/release-notes-generator' }],
   // The crates of the train of the run, whose `paths` hold their folders.
   '@wtf/semantic-release-cargo',
-  ['@wtf/semantic-release-npm', { tarballDir: 'tarballs' }],
-  ['@semantic-release/gitlab', { successCommentCondition: false, failCommentCondition: false }]
+  '@wtf/semantic-release-npm',
+  [
+    '@wtf/semantic-release-trains',
+    {
+      wrap: [
+        '@semantic-release/gitlab',
+        { successCommentCondition: false, failCommentCondition: false }
+      ]
+    }
+  ]
 ]
 ```
 
@@ -69,6 +77,11 @@ The order follows the registries: crates first, then npm, then the GitLab or Git
 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.
 
+The GitLab release of the tag links each crate and each npm package. A crate on crates.io links to
+its page there. A crate on another registry links to the `.crate` file that `cargo publish` packed,
+uploaded to the project's generic package registry. See
+[The links of the release](publishing.md#the-links-of-the-release).
+
 ### What the jobs need
 
 The tag's job needs `cargo` and a credential for the registry: see

package/guides/publishing-go-modules.md

@@ -65,8 +65,16 @@ export const tagPlugins = [
   ['@wtf/semantic-release-trains', { wrap: '@semantic-release/release-notes-generator' }],
   // The Go modules of the train of the run, whose `paths` hold their folders.
   '@wtf/semantic-release-go',
-  ['@wtf/semantic-release-npm', { tarballDir: 'tarballs' }],
-  ['@semantic-release/gitlab', { successCommentCondition: false, failCommentCondition: false }]
+  '@wtf/semantic-release-npm',
+  [
+    '@wtf/semantic-release-trains',
+    {
+      wrap: [
+        '@semantic-release/gitlab',
+        { successCommentCondition: false, failCommentCondition: false }
+      ]
+    }
+  ]
 ]
 ```
 
@@ -243,6 +251,8 @@ With `proxy: true`, the plugin asks the Go proxy for each module once its tag is
 `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.
+The GitLab release of the tag links each module to its page there. Without the proxy, it links each
+module to its folder at the module's own tag. See [The links of the release](publishing.md#the-links-of-the-release).
 
 `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`:

package/guides/publishing-maven.md

@@ -84,10 +84,24 @@ export const tagPlugins = [
   ['@wtf/semantic-release-trains', { wrap: '@semantic-release/release-notes-generator' }],
   // The modules of the train of the run, whose `paths` hold their folders.
   ['@wtf/semantic-release-maven', { args: ['-s', 'ci_settings.xml'] }],
-  ['@semantic-release/gitlab', { successCommentCondition: false, failCommentCondition: false }]
+  // The GitLab release of the tag, linked to each module: its page on Maven Central, or on GitLab.
+  [
+    '@wtf/semantic-release-trains',
+    {
+      wrap: [
+        '@semantic-release/gitlab',
+        { successCommentCondition: false, failCommentCondition: false }
+      ]
+    }
+  ]
 ]
 ```
 
+The GitLab release of the tag links each module that the release deployed. A module on Maven
+Central links to its page on `central.sonatype.com`. A module in a GitLab Maven registry links to
+its page on GitLab. A module in another repository links to its jar, uploaded to the project's
+generic package registry. See [The links of the release](publishing.md#the-links-of-the-release).
+
 ### What the jobs need
 
 The tag's job needs Node for semantic-release, and Maven and a JDK for the deploys. Use an image

package/guides/publishing.md

@@ -42,7 +42,8 @@ export default {
 ```
 
 The plugin does not create the release on GitLab or GitHub. List `@semantic-release/gitlab` or
-`@semantic-release/github` after it.
+`@semantic-release/github` after it. Wrapped in the trains plugin, `@semantic-release/gitlab` links each
+package that the release published: see [The links of the release](#the-links-of-the-release).
 
 | Option       | Default                                  | What it does                                                                                                                                                                                                         |
 | ------------ | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -55,8 +56,8 @@ The plugin does not create the release on GitLab or GitHub. List `@semantic-rele
 | `conditions` | `['source']`                             | The export conditions that point at source files. No tarball ships them.                                                                                                                                             |
 | `check`      | `true`                                   | Check the packages before the first publish. See [What the check catches](#what-the-check-catches).                                                                                                                  |
 | `aside`      | none                                     | Package names to publish under their major's line when their dist-tag points above the release: `release-<major>.x` in place of `latest`, `<dist-tag>-<major>.x` in place of another.                                |
-| `tarballDir` | a folder in the system's temporary files | Where to keep the tarballs after the release, for example as assets of the GitLab or GitHub release. Add a folder in the repo to `.gitignore`. A CI job starts with it empty.                                        |
-| `pack`       | none                                     | Folders or globs of private packages in the train. The plugin packs them into `tarballDir` beside the others and never publishes them. Use it for a demo or another release asset.                                   |
+| `tarballDir` | a folder in the system's temporary files | Where to keep the tarballs after the release, for the links of a package in `pack` or on a registry with no page. Add a folder in the repo to `.gitignore`. A CI job starts with it empty.                           |
+| `pack`       | none                                     | Folders or globs of private packages in the train. The plugin packs them into `tarballDir` beside the others and never publishes them. The GitLab release links each one's tarball. Use it for a demo.               |
 | `distTag`    | the channel's                            | One dist-tag for every package, in place of the channel's, for a one-off release. An empty string means no override.                                                                                                 |
 | `smoke`      | `false`                                  | `true`, or `{ forbid }` with globs that no tarball may hold. Installs each packed package as a consumer would, in `prepare`, before the tag. See [Smoke-test the packages](#smoke-test-the-packages-before-the-tag). |
 
@@ -218,6 +219,47 @@ token in its config, such as `//registry.npmjs.org/:_authToken=${NPM_TOKEN}` in
 publish with another tool, choose another [publisher](#publishers). The recipes at the end show the
 GitLab package registry and JSR.
 
+## The links of the release
+
+The plugin records each package that `publish` published. Wrap `@semantic-release/gitlab` in the
+trains plugin, after the plugins that publish, and the GitLab release of the tag gets a link to
+each package of the train, in every ecosystem that the run published. The config lists no `assets`:
+
+```js norun
+// release.config.mjs: the run of the tag.
+export const tagPlugins = [
+  ['@wtf/semantic-release-trains', { wrap: '@semantic-release/release-notes-generator' }],
+  '@wtf/semantic-release-npm',
+  ['@wtf/semantic-release-trains', { wrap: '@semantic-release/gitlab' }]
+]
+```
+
+Each link has the type `package` and is named after the package. A package gets the first of these
+that it has:
+
+1. **Its page on a public registry**, at the version: `https://www.npmjs.com/package/<name>/v/<version>`
+   for npm, `https://crates.io/crates/<name>/<version>` for crates.io,
+   `https://central.sonatype.com/artifact/<groupId>/<artifactId>/<version>` for Maven Central, and
+   `https://pkg.go.dev/<module>@v<version>` for a Go module when `proxy` asked the Go proxy for it.
+2. **Its page on GitLab**, for a package published to a GitLab package registry: a `registry` or
+   `publishConfig.registry` such as `…/api/v4/projects/<id>/packages/npm/`, or the Maven registry
+   that a module deploys to. After the publish, the plugin looks the package up with the Packages
+   API of that project, or of the group for a group registry, which finds the project that holds
+   it. It uses the run's token, as the GitLab plugin does: `GITLAB_TOKEN` or `GL_TOKEN`, else
+   `CI_JOB_TOKEN`. It sends no token to a GitLab other than the project's. A package that it does
+   not find fails the release (`EGITLABPACKAGE`): run the tag's release again once it is there.
+3. **Its file**, uploaded to the project's generic package registry, as the train's package at the
+   release's version: the tarball of a package in `pack`, which is packed and never published, or
+   of a registry with no page, which `tarballDir` keeps for the link; the `.crate` of a crate on
+   another registry; the jar of a Maven module in a repository that is neither Maven Central nor
+   GitLab.
+4. **Its folder at its tag**, for a Go module that the proxy was not asked for.
+
+A package with none of these fails the release (`ERELEASELINK`), and the error says how to keep a
+file for it. Nothing is uploaded to the project's markdown uploads, and a tarball that no link needs
+is attached nowhere. When the config gives the GitLab plugin `assets` of its own, the release gets
+only those.
+
 ## When a publish fails
 
 How you finish a failed publish depends on where the publish ran.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtf/release-docs",
-  "version": "8.2.3",
+  "version": "9.0.0",
   "description": "The guides of semantic-release for monorepos of more than one ecosystem, released in trains, and the API reference of its packages, which TypeDoc writes: the release of docs commits the reference and publishes it with the guides.",
   "keywords": [
     "documentation",
@@ -38,20 +38,20 @@
   "devDependencies": {
     "@standard-schema/spec": "^1.1.0",
     "@types/node": "^24.10.0",
-    "@wtf/release-cargo": "3.1.1",
-    "@wtf/release-go": "1.0.0",
-    "@wtf/release-maven": "1.0.0",
-    "@wtf/release-npm": "1.1.1",
+    "@wtf/release-cargo": "3.2.0",
+    "@wtf/release-go": "1.1.0",
+    "@wtf/release-maven": "1.1.0",
+    "@wtf/release-npm": "1.2.0",
     "@wtf/release-replace": "4.0.0",
     "@wtf/release-system": "1.0.1",
-    "@wtf/release-trains": "7.1.1",
+    "@wtf/release-trains": "8.0.0",
     "@wtf/release-validate": "4.0.0",
-    "@wtf/semantic-release-cargo": "3.1.1",
-    "@wtf/semantic-release-go": "1.0.0",
-    "@wtf/semantic-release-maven": "1.0.0",
-    "@wtf/semantic-release-npm": "1.1.1",
+    "@wtf/semantic-release-cargo": "3.2.0",
+    "@wtf/semantic-release-go": "1.1.0",
+    "@wtf/semantic-release-maven": "1.1.0",
+    "@wtf/semantic-release-npm": "1.2.0",
     "@wtf/semantic-release-replace": "4.0.0",
-    "@wtf/semantic-release-trains": "7.1.1",
+    "@wtf/semantic-release-trains": "8.0.0",
     "@wtf/semantic-release-validate": "4.0.0",
     "ajv": "^8.20.0",
     "semantic-release": "^25.0.9",