@wtf/release-docs 8.2.1 → 8.2.3

package/guides/validating-a-config.md

@@ -1,25 +1,34 @@
-# Validating a config
-
-Each package owns one part of a config of semantic-release, and checks it two ways: as a validator,
-for code, and as a JSON Schema, for an editor. The parts compose into the schema of a whole config.
-
-| Package                          | Its part of a config                                              |
-| -------------------------------- | ----------------------------------------------------------------- |
-| `@wtf/release-trains`            | The root `trains`, `train` and `dependencies`                     |
-| `@wtf/semantic-release-trains`   | Its entries of `plugins`, each of `wrap`, `generated`, or neither |
-| `@wtf/semantic-release-npm`      | Its entries of `plugins`                                          |
-| `@wtf/semantic-release-validate` | Its entries of `plugins`                                          |
-| `@wtf/semantic-release-replace`  | The root `templates`, and its entries of `plugins`                |
-
-A part constrains only what it owns, an entry of `plugins` by the name of the plugin, as
-`["@wtf/semantic-release-npm", { "access": "public" }]`, and takes anything else: the
-other plugins, the other options of the root, and `$schema`.
-
-## In an editor: `schema.json`
-
-Each package publishes its part as a JSON Schema of draft 2020-12, `schema.json`, which names itself
-by its file (`"$id": "schema.json"`) and refers to nothing outside itself. Compose them in a
-`release.schema.json` of the repo, by `allOf`, one `$ref` for each package the repo installs:
+# Validate a config
+
+You can check a semantic-release config in three places: in your editor, in code, and in each run.
+Each package owns one part of the config and checks that part in two ways: as a validator for code,
+and as a JSON Schema for an editor. The parts compose into a schema for the whole config.
+
+| Package                          | Its part of a config                                                     |
+| -------------------------------- | ------------------------------------------------------------------------ |
+| `@wtf/release-trains`            | The root `trains`, `ecosystems`, `train`, `dependencies` and `cascade`   |
+| `@wtf/semantic-release-trains`   | Its entries in `plugins`: with `wrap`, with `generated`, or with neither |
+| `@wtf/semantic-release-npm`      | Its entries in `plugins`                                                 |
+| `@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-validate` | Its entries in `plugins`                                                 |
+| `@wtf/semantic-release-replace`  | The root `templates`, and its entries in `plugins`                       |
+
+A part constrains only what it owns. It finds its entries in `plugins` by the plugin's name, as in
+`["@wtf/semantic-release-npm", { "access": "public" }]`. It accepts anything else: the other
+plugins, the other root options, and `$schema`.
+
+## Check a config in your editor with `schema.json`
+
+Each package publishes its part as a JSON Schema (draft 2020-12) in `schema.json`. The schema names
+itself by its file (`"$id": "schema.json"`) and refers to nothing outside itself.
+
+Compose the parts in a `release.schema.json` in your repo with `allOf`. Add one `$ref` for each
+package that the repo installs, and leave out the others. This repo releases npm packages and Cargo
+crates, so it adds the schemas of the npm and the cargo plugins. A repo with Go modules or Maven
+modules adds `@wtf/semantic-release-go/schema.json` or `@wtf/semantic-release-maven/schema.json` in
+the same way:
 
 ```json
 {
@@ -28,28 +37,31 @@ by its file (`"$id": "schema.json"`) and refers to nothing outside itself. Compo
     { "$ref": "./node_modules/@wtf/release-trains/schema.json" },
     { "$ref": "./node_modules/@wtf/semantic-release-trains/schema.json" },
     { "$ref": "./node_modules/@wtf/semantic-release-npm/schema.json" },
+    { "$ref": "./node_modules/@wtf/semantic-release-cargo/schema.json" },
     { "$ref": "./node_modules/@wtf/semantic-release-validate/schema.json" },
     { "$ref": "./node_modules/@wtf/semantic-release-replace/schema.json" }
   ]
 }
 ```
 
-and point the config at it:
+Then point the config at it. The config names each ecosystem by its plugin's `./ecosystem`, as in
+[How ecosystems work](ecosystems.md):
 
 ```json
 {
   "$schema": "./release.schema.json",
-  "ecosystems": ["@wtf/release-npm"],
+  "ecosystems": ["@wtf/semantic-release-npm/ecosystem", "@wtf/semantic-release-cargo/ecosystem"],
   "trains": {
-    "validate": { "paths": ["packages/release-validate", "packages/semantic-release-validate"] }
+    "validate": { "paths": ["packages/release-validate", "packages/semantic-release-validate"] },
+    "runtime": { "paths": ["crates/runtime"] }
   },
   "plugins": [["@wtf/semantic-release-trains", { "wrap": "@semantic-release/commit-analyzer" }]]
 }
 ```
 
-semantic-release gives every plugin `$schema` as an option of the root, and each part takes it.
+semantic-release gives every plugin `$schema` as a root option, and each part accepts it.
 
-Or map the files in the settings of VS Code, with no `$schema` in the config:
+Or map the files in your VS Code settings, with no `$schema` in the config:
 
 ```json
 {
@@ -66,15 +78,17 @@ Or map the files in the settings of VS Code, with no `$schema` in the config:
 }
 ```
 
-A JSON Schema says the shape of a config. What it cannot say, as two trains of one tag format, or a
-folder of two trains, the validators say, and the plugins check before a run releases.
+A JSON Schema describes the shape of a config. It cannot express every rule, such as two trains
+with one tag format, or a folder in two trains. The validators check those rules, and the plugins
+run the validators before a run releases.
+
+## Check a config in code with `./schema`
 
-## In code: `./schema`
+Each package's `./schema` export holds the same part as a validator, `configSchema`. It also holds
+the validator for the options of each of its plugins, which the plugin runs in `verifyConditions`.
 
-Each package's `./schema` has the same part as a validator, `configSchema`, and the validator of the
-options each of its plugins is given, as the plugin checks them in `verifyConditions`. Each is a
-[Standard Schema](https://standardschema.dev), which any library of the standard runs, and a
-Standard JSON Schema, which gives its JSON Schema:
+Each validator is a [Standard Schema](https://standardschema.dev), so any library that supports the
+standard can run it. Each one is also a Standard JSON Schema, which gives its JSON Schema:
 
 ```ts
 import { configSchema } from '@wtf/release-trains/schema'
@@ -85,19 +99,21 @@ for (const issue of result.issues ?? []) console.error(issue.path, issue.message
 export const json = configSchema['~standard'].jsonSchema.input({ target: 'draft-2020-12' })
 ```
 
-`schema.json` is that JSON Schema, which the package exports as `<package>/schema.json`, to import
-`with { type: 'json' }`.
+`schema.json` is that JSON Schema. The package exports it as `<package>/schema.json`, so you can
+import it `with { type: 'json' }`.
 
-A plugin checks its options with its validator, whether or not the config has a schema: each fault
-is an error of its code (`EOPTIONS`, or a code of the trains, as `ETRAINPATHS`) that says where it
-is, and every fault is told at once.
+A plugin checks its options with its validator, whether or not the config has a schema. Each fault
+is an error with a code, such as `EOPTIONS` or a trains code like `ETRAINPATHS`. The error says
+where the fault is, and the plugin reports every fault at once.
 
-## In a run: rules of your own
+## Check each run against rules of your own
 
-`@wtf/semantic-release-validate` validates the config of a run by a Standard Schema of your own,
-before it releases: a schema of Zod, Valibot or ArkType, or one of a JSON Schema. List it first, once
-for each schema, with the schema or the module whose default export is one, by its path from the
-root of the repo:
+`@wtf/semantic-release-validate` validates the config of a run against a Standard Schema of your
+own, before the run releases. The schema can come from Zod, Valibot or ArkType, or from a JSON
+Schema.
+
+List the plugin first, once for each schema. Give it the schema, or a module whose default export
+is one, by its path from the root of the repo:
 
 ```js train=validate
 // release.config.mjs
@@ -112,17 +128,25 @@ export default {
 }
 ```
 
-Each issue fails the run with `ECONFIG`, where it is, all at once; a schema it cannot load, with
-`ESCHEMA`. The schema gets the config as it was written, `plugins` too, so a rule may hold the
-entries of `plugins`, as "every plugin of the host is on the train", as well as the root, as
-`owner`, `branches` or `trains`. What semantic-release adds to the options it gives a plugin is left
-out (`configOf` of the plugin): what the parser of its command line leaves, `_`, `$0`, `b`,
-`dry-run` and the like, and `originalRepositoryURL`. The defaults it gives `branches`,
-`repositoryUrl`, `tagFormat` and `plugins` stay, and `dryRun`, which a run outside of a CI sets.
+Each issue fails the run with `ECONFIG` and says where it is. The plugin reports all issues at
+once. A schema that it cannot load fails with `ESCHEMA`.
+
+The schema gets the config as you wrote it, `plugins` included. So a rule can check the entries in
+`plugins`, such as "every host plugin is wrapped by the trains plugin". It can also check root
+options, such as `owner`, `branches` or `trains`.
+
+The plugin leaves out what semantic-release adds to the options it gives a plugin (`configOf` in
+the plugin):
+
+- What the command-line parser leaves behind: `_`, `$0`, `b`, `dry-run` and the like.
+- `originalRepositoryURL`.
+
+The defaults that semantic-release gives `branches`, `repositoryUrl`, `tagFormat` and `plugins`
+stay. So does `dryRun`, which a run outside CI sets.
 
-`fromJsonSchema` of `@wtf/release-validate/json-schema` makes a Standard Schema of a JSON Schema, by
-the engine you give it, as Ajv, so the rules of a house can be one JSON Schema, which an editor reads
-too:
+`fromJsonSchema` from `@wtf/release-validate/json-schema` makes a Standard Schema from a JSON
+Schema, with an engine you give it, such as Ajv. So your house rules can be one JSON Schema, which
+an editor reads too:
 
 ```js fragment
 // release/house-rules.mjs
@@ -136,5 +160,6 @@ const ajv = new Ajv2020({ allErrors: true })
 export default fromJsonSchema(houseRules, (schema) => ajv.compile(schema))
 ```
 
-Each error of the engine is an issue, its `instancePath` its path. The library depends on no engine,
-and the plugin on no library of schemas: the repo installs the one it uses.
+Each error from the engine becomes an issue, with its `instancePath` as the issue's path. The
+library depends on no engine, and the plugin depends on no schema library. Your repo installs the
+one it uses.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtf/release-docs",
-  "version": "8.2.1",
+  "version": "8.2.3",
   "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",