@xmachines/docs 6.1.0 → 7.1.0

package/contributing/configuration.md

@@ -20,33 +20,6 @@ The dev container currently defines no workspace-specific environment variables;
 
 **Defined in:** the `test:dist` and `test:browser:dist` scripts of the root `package.json`. **Read by:** `xmTestTarget` of [`@xmachines/shared/vite-aliases`](../api/@xmachines/shared/README.md), which every config helper of that package calls. Do not set it by hand: run `pnpm run test:dist`. See [testing.md](testing.md#tests-on-the-build-output).
 
-### CI / Release Pipeline Variable
-
-| Variable            | Required | Default                      | Description                                                                                                                                                                         |
-| ------------------- | -------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `SEMREL_SKIP_STEPS` | Optional | `""` (empty — run all steps) | A single RegExp string matched against every semantic-release plugin step ID. Use `\|` for alternation to skip multiple steps. Set via the GitLab "Run pipeline" UI or API trigger. |
-
-**Defined in:** `.gitlab-ci.yml`, consumed by `release.config.mjs`.
-
-**Examples:**
-
-A step ID is the name of the plugin, and a name that the entry declares extends it: `@semantic-release/exec:build`.
-
-```bash
-# Skip one prepare step
-SEMREL_SKIP_STEPS="@semantic-release/exec:build$"
-
-# Skip every prepare step
-SEMREL_SKIP_STEPS="@semantic-release/exec"
-
-# Leave CHANGELOG.md alone
-SEMREL_SKIP_STEPS="@semantic-release/changelog"
-```
-
-A pattern that removes `@semantic-release/git` throws instead of running: semantic-release would still tag and push, and the tag would then name a commit that carries no version bump.
-
-The variable reaches the publish never. `scripts/publish-release.mjs` runs on the tag pipeline, outside semantic-release — see [deployment.md](deployment.md).
-
 ---
 
 ## Configuration Files
@@ -104,19 +77,20 @@ All packages extend this base. Key compiler settings:
 | `exactOptionalPropertyTypes` | `true`       |                                                          |
 | `declaration`                | `true`       | Emits `.d.ts` files                                      |
 | `declarationMap`             | `true`       | Emits `.d.ts.map` for IDE go-to-source                   |
+| `emitDeclarationOnly`        | `true`       | tsc emits no JavaScript: the Vite pass ships it          |
 | `sourceMap`                  | `true`       |                                                          |
 | `verbatimModuleSyntax`       | `true`       | Preserves `import type`                                  |
 | `isolatedModules`            | `true`       |                                                          |
 | `removeComments`             | `false`      | Preserves JSDoc in output                                |
 
-**Two passes emit, and `emitDeclarationOnly` decides which one ships.** `build` is
-`vite build && tsc --build`, so tsc runs last.
+**Vite writes the JavaScript, and tsc writes the declarations.** `build` is
+`vite build && tsc --build`. The shared tsconfig sets `emitDeclarationOnly`, so tsc emits
+only `.d.ts` and `.d.ts.map`, and the Vite pass is the published `dist/*.js` of every
+package. `build.target` governs it.
 
-- **Fourteen publishable packages** let tsc emit JavaScript. tsc overwrites the Vite pass,
-  and `compilerOptions.target` above is what governs the published `dist/*.js`.
-- **Five** — play-vue, play-svelte, play-solid, play-solid-router,
-  play-tanstack-solid-router — set `emitDeclarationOnly`, so tsc emits only `.d.ts` and the
-  Vite pass is the published JavaScript. `build.target` governs theirs.
+Vite emits a module that holds only types as no file. Its `.d.ts` still ships. A test that
+imports such a module by path, or an internal re-export module that no entry reaches, fails
+in the dist run: import the module that holds the code.
 
 Vite inherits no target from the tsconfig. It reads `compilerOptions.target` for one
 purpose: to pick the `useDefineForClassFields` default that it gives the transform. The
@@ -126,7 +100,7 @@ explicit browser list for a demo app.
 
 Leave both stated, and keep both at ESNext for a library. A package that inherits the Vite
 default builds against a browser baseline, which is a second and lower ceiling than the one
-this table declares — and it is the ceiling that ships for those five.
+this table declares — and it is the ceiling that ships.
 
 **A demo states an explicit browser list, and not `baseline-widely-available`.** A target
 controls syntax and adds no method. `baseline-widely-available` of Vite 8 names
@@ -165,6 +139,9 @@ The root config extends the shared base ([`@xmachines/shared/oxlint`](../api/@xm
 
 ```typescript
 // /oxlint.config.ts
+import sharedConfig from "@xmachines/shared/oxlint";
+import { defineConfig } from "oxlint";
+
 export default defineConfig({
 	extends: [sharedConfig],
 	ignorePatterns: [
@@ -229,6 +206,9 @@ The root config extends the shared base and adds workspace-level ignore patterns
 
 ```typescript
 // /oxfmt.config.ts
+import sharedConfig from "@xmachines/shared/oxfmt";
+import { defineConfig } from "oxfmt";
+
 export default defineConfig({
 	...sharedConfig,
 	ignorePatterns: [
@@ -362,7 +342,7 @@ Root Vitest config is a **workspace coordinator** that lists all per-package con
 
 Coverage provider: `v8`. Individual packages may declare higher per-package thresholds in their own `vitest.config.ts`.
 
-The JUnit file is `test-results.xml`. The dist run (`XM_TEST_TARGET=dist`) writes `test-results-dist.xml`, and it prefixes each class name with `dist:`, so the two runs stay apart in the merge request widget.
+The JUnit file is `test-results.xml`. CI runs the suites on the build output alone (`XM_TEST_TARGET=dist`), so each test counts one time in the merge request widget. In the dist run, `coverage.include` also names `packages/*/dist/**/*.js`, and `excludeAfterRemap` filters again after the source maps name the files of `src/`. The dist run leaves out the `doc-examples` project: `pnpm run test:docs:examples` runs it.
 
 **Browser test config:** `/vitest.browser.config.ts`
 Run with `pnpm run test:browser`, or with `pnpm run test:browser:dist` against the build output. Uses Playwright Chromium via Vitest browser mode. `testTimeout` is `20000` ms; `maxWorkers` is `2` (default; demo integration projects override with `pool: "threads"` + `maxWorkers: 2`).
@@ -413,40 +393,42 @@ Provides the helpers used in all `vitest.config.ts` and `vite.config.ts` files:
 **Location:** `/release.config.mjs`
 **Tool:** [semantic-release](https://semantic-release.gitbook.io/) via `@semantic-release/*` plugins
 
-Defines the release branches and plugin chain used by the GitLab CI semantic-release job.
+Defines the trains, the release branches, and the plugins of each run: the run of a branch, of the `semantic-release` job of a train, and the run of a tag, of the `publish-release` job. The `to-be-continuous` semantic-release component turns it into `.releaserc.json` and installs each plugin it names, so it is literals: no import of a plugin, no top-level await.
 
 **Release branches:**
 
 | Branch  | Channel   | Pre-release |
 | ------- | --------- | ----------- |
 | `main`  | (default) | No          |
+| `next`  | `next`    | `next`      |
 | `rc`    | `rc`      | `rc`        |
 | `beta`  | `beta`    | `true`      |
 | `alpha` | `alpha`   | `alpha`     |
 | `pre`   | `pre`     | `pre`       |
 
-Only `main` is a protected branch today. That works because `GITLAB_TOKEN` — which the release needs, since `CI_JOB_TOKEN` can push neither the release commit nor the tag — is an _unprotected_ group variable and so reaches every one of these refs. If it is ever made protected, each of these branches has to be protected too, or the release fails in verify-conditions with `EGITNOPERMISSION` rather than at the registry.
+`GITLAB_TOKEN`, which the release needs (`CI_JOB_TOKEN` can push neither the release commit nor the tag, and creates no GitLab release), is a _protected_ group variable: it reaches only protected branches and protected tags. Every release branch is protected, `main` and the prerelease branches alike, and so are the tags of the trains, `core-v*`, `play-v*` and `docs-v*`. A release branch added to this table has to be protected too, or its release fails in verify-conditions with `EGITNOPERMISSION`.
 
-**Tag format:** `v${version}`
+**Trains:** `core` (`packages/core`), `play` (`packages/play`, `packages/play-*`) and `docs` (`packages/docs`, with every file of `core` and `play` counting for it too). The build files of the root and `packages/shared` count for every train.
 
-**Plugin order:**
+**Tag format:** `<train>-v${version}`, as `play-v7.1.0`.
 
-1. `@semantic-release/commit-analyzer` — determines version bump from conventional commits
-2. `@semantic-release/release-notes-generator` — builds release notes
-3. `@semantic-release/changelog` — writes `CHANGELOG.md`
-4. `@semantic-release/exec` steps (in order):
+**Plugin order of a branch's run:**
+
+1. `@semantic-release/commit-analyzer` and `@semantic-release/release-notes-generator`, each wrapped by an entry of `@wtf/semantic-release-trains` (`wrap`) — the version bump and the notes, of the train's commits alone; each entry of the trains plugin also checks the trains
+2. `@semantic-release/changelog` — writes the `CHANGELOG.md` of the train's first path
+3. `@wtf/semantic-release-replace` — writes the version into the badge of each README of the train, by the `badge` template at the root of the config
+4. Of `docs` alone, `@semantic-release/exec` steps (in order):
     - `corepack` — `corepack enable`
     - `install` — `pnpm install --frozen-lockfile`
-    - `set-workspace-versions` — updates all `package.json` files to the new version
     - `build` — `pnpm run build`
-    - `typedoc` — `pnpm --filter @xmachines/docs run typedoc`
+    - `typedoc` — `pnpm --filter @xmachines/docs run typedoc --gitRevision docs-v${nextRelease.version}`
     - `format-docs` — `pnpm --filter @xmachines/docs run format`
-    - `stage-generated-docs` — `git add -A packages/docs/api packages/docs/examples/@xmachines packages/docs/examples/README.md`, so a page that TypeDoc deleted leaves git too
-5. `@semantic-release/git` — commits the changelog, the manifests, the READMEs and the generated docs (`api/`, `examples/@xmachines/` and the demo lists of `examples/README.md`), then pushes the commit and the tag
 
-The list ends there. semantic-release publishes nothing and creates no GitLab release: `scripts/publish-release.mjs` does both, on the pipeline of the tag. [deployment.md](deployment.md) states the whole sequence and the reason.
+    then an entry of `@wtf/semantic-release-trains` of `generated: true`, which stages the trees that TypeDoc writes, so a page that TypeDoc deleted leaves git too
+
+5. `@semantic-release/git` — commits the changelog, the READMEs of the train, and of `docs` the generated docs (`api/`, `examples/@xmachines/` and the demo lists of `examples/README.md`), then pushes the commit and the tag
 
-Any step above can be skipped with the `SEMREL_SKIP_STEPS` CI variable, which the CI / Release Pipeline Variable section at the top of this page states.
+**Plugin order of a tag's run:** the notes generator on the train; `@wtf/semantic-release-trains-publish`, which packs, smoke-tests and publishes the train's packages and packs its demos; `@semantic-release/gitlab`, the GitLab release with the tarballs. [deployment.md](deployment.md) states the whole sequence and the reason.
 
 ---
 
@@ -459,10 +441,11 @@ Renovate updates the npm dependencies of every package of the workspace, the dem
 
 The rules of the file:
 
-- **Three days of cooldown.** The renovate component waits 3 days for a new version, which also covers the cooldown of one day in pnpm 11. The `@xmachines/*` packages have no cooldown, as in `pnpm-workspace.yaml`.
+- **Three days of cooldown.** The renovate component waits 3 days for a new version, which also covers the cooldown of one day in pnpm. The `@xmachines/*` packages have no cooldown, as in `pnpm-workspace.yaml`.
 - **One merge request for json-render.** The `@xmachines/json-render-*` packages move together. The merge request moves every range, the `peerDependencies` too, as a `feat(deps):` commit. Renovate proposes the prereleases of the fork (`0.22.0-xm.1`), which it skips by default. Update the ranges that the README files name on the branch of that merge request.
-- **No new major for an audit floor.** An override with a major in its key, for example `brace-expansion@2`, gets no update to the next major.
-- **Approval for a patched package.** `pnpm-workspace.yaml` patches `@testing-library/jest-dom` and `@vitest/mocker` at one version. An update of these packages, or of vitest, needs a new patch. Approve it in the Dependency Dashboard, then move the patch on its branch.
+- **No new major for an override of one major.** An override with a major in its key, for example `zod@4`, gets no update to the next major.
+- **Approval for a patched package.** `pnpm-workspace.yaml` patches `@testing-library/jest-dom` at one version. An update of that package needs a new patch. Approve it in the Dependency Dashboard, then move the patch on its branch.
+- **Approval for a TypeScript major.** A new major of `typescript` waits in the Dependency Dashboard. typedoc reads the TypeScript API, and it declares the majors that it supports. The `docs` job is manual in a merge request, so a green pipeline does not show the fault. Approve the update when typedoc supports the new major.
 - **Commit types.** A component update is a `ci:` commit, so semantic-release makes no release from it. An npm update is a `fix(deps):` commit for a `dependencies` entry, and a `chore(deps):` commit for any other type.
 
 A new version of a component can rename an input and not say so. A pipeline that fails with no job is then an error in the inputs. Compare the inputs in `.gitlab-ci.yml` with the `spec` of the new version before you merge.
@@ -479,15 +462,14 @@ The only environment-specific distinction is between **local development** (dev
 
 ## Required vs Optional Settings Summary
 
-| Config                                                                     | Required to Work                        | Optional / Has Default        |
-| -------------------------------------------------------------------------- | --------------------------------------- | ----------------------------- |
-| `SEMREL_SKIP_STEPS`                                                        | No                                      | Default: `""` (run all steps) |
-| Root `tsconfig.json` `references`                                          | Yes — the whole build order             | —                             |
-| Per-package `references`                                                   | No — TypeScript drops them on `extends` | —                             |
-| Per-package `composite: true`                                              | Yes — required for project references   | —                             |
-| [`@xmachines/shared/tsconfig`](../api/@xmachines/shared/README.md) extends | Yes — all packages must extend it       | —                             |
-| [`@xmachines/shared/oxlint`](../api/@xmachines/shared/README.md) extends   | Yes — all packages must extend it       | —                             |
-| [`@xmachines/shared/oxfmt`](../api/@xmachines/shared/README.md) extends    | Yes — all packages must extend it       | —                             |
+| Config                                                                     | Required to Work                        | Optional / Has Default |
+| -------------------------------------------------------------------------- | --------------------------------------- | ---------------------- |
+| Root `tsconfig.json` `references`                                          | Yes — the whole build order             | —                      |
+| Per-package `references`                                                   | No — TypeScript drops them on `extends` | —                      |
+| Per-package `composite: true`                                              | Yes — required for project references   | —                      |
+| [`@xmachines/shared/tsconfig`](../api/@xmachines/shared/README.md) extends | Yes — all packages must extend it       | —                      |
+| [`@xmachines/shared/oxlint`](../api/@xmachines/shared/README.md) extends   | Yes — all packages must extend it       | —                      |
+| [`@xmachines/shared/oxfmt`](../api/@xmachines/shared/README.md) extends    | Yes — all packages must extend it       | —                      |
 
 ---