@wtf/release-docs 9.0.2 → 9.1.0

package/guides/ecosystems.md

@@ -14,15 +14,16 @@ An ecosystem is a module that reads one kind of manifest, such as npm's `package
   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
+Five 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                            |
+| 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                                                          |
+| `oci`     | `@wtf/release-oci`   | `@wtf/semantic-release-oci`   | each `Dockerfile`, `Containerfile` or `.devcontainer/devcontainer.json` that git tracks |
 
 ## Name the ecosystems in your config
 
@@ -189,6 +190,24 @@ own.
 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).
 
+### OCI images
+
+`@wtf/release-oci` reads each folder of a file an image is built of that git tracks: a
+`Dockerfile`, a `Containerfile`, or a `.devcontainer/devcontainer.json`, which the devcontainer CLI
+builds. A folder of more than one is one image. It reads a commit's files with `git ls-tree`.
+
+- **Name:** the image's repository in its registry: the registry image of the project,
+  `CI_REGISTRY_IMAGE` of a pipeline, for the image at the root, and that and its folder for another.
+  Where the environment names no registry image, the image is named by its folder.
+- **Published:** every image.
+- **Kinds:** none. An image does not depend on another image of the repo as the trains read it: a
+  `FROM` or a base pins a tag of a registry. Order such trains by `dependsOn`.
+- **`resolve`:** the version itself, the tag a release publishes.
+- **`satisfies`:** a tag of the one version it names.
+
+A release copies the image a pipeline tested, by its digest, to the tags of the version, and moves
+the minor and the major of a release. See [Publish OCI images](publishing-oci.md).
+
 ## Write your own ecosystem
 
 Write an ecosystem when your repo holds a kind of package that none of the built-in ecosystems

package/guides/getting-started.md

@@ -18,14 +18,15 @@ 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:
+depends on, and what a version range means. Five 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)   |
+| 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)   |
+| OCI       | each `Dockerfile`, `Containerfile` or `.devcontainer/devcontainer.json` | `@wtf/semantic-release-oci`   | [Publish OCI images](publishing-oci.md)        |
 
 You can also write an ecosystem of your own for any other kind of package. See
 [How ecosystems work](ecosystems.md).
@@ -46,8 +47,9 @@ The libraries:
   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-npm`, `@wtf/release-cargo`, `@wtf/release-go`, `@wtf/release-maven` and
+  `@wtf/release-oci` are the five 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.
 
@@ -55,8 +57,9 @@ 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-npm`, `@wtf/semantic-release-cargo`, `@wtf/semantic-release-go`,
+  `@wtf/semantic-release-maven` and `@wtf/semantic-release-oci` 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.
 

package/guides/publishing-oci.md

@@ -0,0 +1,103 @@
+# Publish OCI images
+
+[`@wtf/semantic-release-oci`](../../semantic-release-oci/README.md) releases the OCI images of a repo
+that belong to a train: container images, built by Docker, buildah or the devcontainer CLI. Use it
+when a train holds images, 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.
+
+A release never rebuilds an image. The pipeline of the tag builds and tests each image, as it does
+on every branch; the release then copies that tested image, by its digest, to the tags of its
+version. The bytes released are the bytes tested, and a consumer pins a version, or a major that
+moves, instead of a commit.
+
+The plugin runs on the library [`@wtf/release-oci`](../../release-oci/README.md). The library's
+default export is the OCI ecosystem, and the plugin exports the same ecosystem at `./ecosystem`. Add
+`'@wtf/semantic-release-oci/ecosystem'` to `ecosystems` in your config. The trains then treat images
+the same way as npm packages: they decide which train holds each image, the order of the trains,
+and the checks of a release. See [How ecosystems work](ecosystems.md).
+
+## Turn it on
+
+### Build and test each image in the pipeline of the tag
+
+An image is each folder that holds a `Dockerfile`, a `Containerfile` or a
+`.devcontainer/devcontainer.json` that git tracks. The pipeline of the tag builds it, tests it, and
+pushes it as a snapshot before the release publishes: the plugin copies that snapshot. By default it
+is `<image>/snapshot:<CI_COMMIT_REF_SLUG>`, as the devcontainer component of
+[wetryfun/devops/components](https://gitlab.com/wetryfun/devops/components) pushes it. Another
+pipeline names its own with `sourceRepository` and `sourceTag`.
+
+### Add the OCI ecosystem and the plugin
+
+An image belongs to the train whose `paths` hold its folder. Its repository in the registry is the
+registry image of the project, `CI_REGISTRY_IMAGE` of a pipeline, for an image at the root, and
+that and its folder for another, as `registry.gitlab.com/acme/images/base` of a folder `base`.
+
+```js norun
+// release.config.mjs
+export default {
+  trains: { base: { paths: ['base'] }, release: { paths: ['release'] } },
+  ecosystems: ['@wtf/semantic-release-oci/ecosystem'],
+  train: process.env.RELEASE_TRAIN,
+  tagFormat: `${process.env.RELEASE_TRAIN}-v\${version}`,
+  plugins: [
+    ['@wtf/semantic-release-trains', { wrap: '@semantic-release/commit-analyzer' }],
+    ['@wtf/semantic-release-oci', { platforms: ['linux/amd64'] }],
+    ['@wtf/semantic-release-trains', { wrap: '@semantic-release/gitlab' }]
+  ]
+}
+```
+
+### Log crane in
+
+The plugin runs [crane](https://github.com/google/go-containerregistry/blob/main/cmd/crane/README.md),
+which copies a digest from one repository to another by mounting its blobs, with no docker and no
+pull. Put crane on the path of the release job and log it in to the registry, as in a pipeline of
+GitLab:
+
+```sh
+echo "$CI_REGISTRY_PASSWORD" | crane auth login --username "$CI_REGISTRY_USER" --password-stdin "$CI_REGISTRY"
+```
+
+## What a release does
+
+`publish`, in the run of the tag:
+
+1. finds the snapshot of each image of the train by its digest, `crane digest`, and the platforms of
+   its index, `crane manifest`. A snapshot the registry has not, or of fewer platforms than
+   `platforms` names, fails the release (`EOCISMOKE`) before anything is copied;
+2. checks the tag of the version: a registry that has it at the same digest skips it, and at another
+   digest refuses the release (`EOCIRETAG`). A released version never moves;
+3. copies the snapshot to the version, then to the minor and the major, which move:
+
+| Version        | Tags                |
+| -------------- | ------------------- |
+| `1.4.2`        | `1.4.2`, `1.4`, `1` |
+| `0.3.1`        | `0.3.1`, `0.3`      |
+| `8.0.0-next.1` | `8.0.0-next.1`      |
+
+4. links each image from the GitLab release of the tag to its page in the container registry of the
+   project, which the Container Registry API names (`EOCILINK`). An image is linked where it lives,
+   never uploaded.
+
+A release that stopped part way is finished by a retry of its job: the version the registry has at
+the same digest is skipped, and the moving tags are copied again.
+
+## Label an image of its version
+
+A release stamps nothing into an image: what was tested ships. A pipeline that labels an image of
+the version it will be, as `org.opencontainers.image.version`, reads the next version of its train
+of the dotenv that `semantic-release-info` writes, and passes it to its build as an argument of its
+own.
+
+## Errors
+
+| Code            | What to do                                                                     |
+| --------------- | ------------------------------------------------------------------------------ |
+| `EOCIECOSYSTEM` | Add `'@wtf/semantic-release-oci/ecosystem'` to `ecosystems`                    |
+| `EOCIIMAGE`     | Run the release in a pipeline of GitLab, or give the plugin `image`            |
+| `EOCISOURCE`    | Run the release in the pipeline of its tag, or give the plugin `sourceTag`     |
+| `EOCISMOKE`     | Build and push the snapshot before the release, and log crane in               |
+| `EOCIRETAG`     | Release a new version: the registry has this one at another digest             |
+| `EOCITAG`       | Give crane a token that may write the repository, and retry the job            |
+| `EOCILINK`      | Give the run a token that may read the registry of the project, `GITLAB_TOKEN` |

package/guides/troubleshooting.md

@@ -77,6 +77,7 @@ own codes:
 - Cargo: [Publish Cargo crates](publishing-crates.md).
 - Go: [Publish Go modules](publishing-go-modules.md).
 - Maven: [Publish Maven modules](publishing-maven.md).
+- OCI images: [Publish OCI images](publishing-oci.md).
 - `@wtf/release-validate`: [Validate a config](validating-a-config.md).
 - `EPUBLISHSMOKE` of `@wtf/release-npm`: [Publish npm packages](publishing.md).
 

package/guides/validating-a-config.md

@@ -12,6 +12,7 @@ and as a JSON Schema for an editor. The parts compose into a schema for the whol
 | `@wtf/semantic-release-cargo`    | Its entries in `plugins`                                                 |
 | `@wtf/semantic-release-go`       | Its entries in `plugins`                                                 |
 | `@wtf/semantic-release-maven`    | Its entries in `plugins`                                                 |
+| `@wtf/semantic-release-oci`      | Its entries in `plugins`                                                 |
 | `@wtf/semantic-release-validate` | Its entries in `plugins`                                                 |
 | `@wtf/semantic-release-replace`  | The root `templates`, and its entries in `plugins`                       |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtf/release-docs",
-  "version": "9.0.2",
+  "version": "9.1.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",
@@ -42,6 +42,7 @@
     "@wtf/release-go": "1.1.0",
     "@wtf/release-maven": "1.1.0",
     "@wtf/release-npm": "1.2.0",
+    "@wtf/release-oci": "1.0.0",
     "@wtf/release-replace": "4.0.0",
     "@wtf/release-system": "1.0.1",
     "@wtf/release-trains": "8.0.2",
@@ -50,6 +51,7 @@
     "@wtf/semantic-release-go": "1.1.0",
     "@wtf/semantic-release-maven": "1.1.0",
     "@wtf/semantic-release-npm": "1.2.0",
+    "@wtf/semantic-release-oci": "1.0.0",
     "@wtf/semantic-release-replace": "4.0.0",
     "@wtf/semantic-release-trains": "8.0.2",
     "@wtf/semantic-release-validate": "4.0.0",