@xmachines/docs 1.0.0-beta.9 → 1.1.0

package/contributing/deployment.md

@@ -0,0 +1,333 @@
+# Deployment
+
+This document describes how `@xmachines/xmachines-js` packages are built, versioned, and published to npm. All releases are automated through [semantic-release](https://semantic-release.gitbook.io/) running inside a GitLab CI pipeline. No manual `npm publish` commands are required for normal releases.
+
+---
+
+## Deployment Targets
+
+All `@xmachines/*` packages are published to the **public npm registry** (`registry.npmjs.org`). Every package uses `"publishConfig": { "access": "public" }` so scoped packages are accessible without an npm org subscription. See the [Published Packages](#published-packages) table for the full list.
+
+| Target          | Config File                                                               | Purpose                                                |
+| --------------- | ------------------------------------------------------------------------- | ------------------------------------------------------ |
+| npm registry    | `release.config.mjs` (npm plugin entries derived from the workspace scan) | Publish all public packages                            |
+| GitLab Releases | `release.config.mjs` (`@semantic-release/gitlab` plugin)                  | Attach tarball artifacts to the GitLab release tag     |
+| GitLab CI       | `.gitlab-ci.yml`                                                          | Trigger builds, tests, and releases on push / MR / tag |
+
+The root `package.json` is marked `"private": true` and is **never published** to npm.
+
+---
+
+## Published Packages
+
+The following packages are published on every release (derived from the workspace scan in `release.config.mjs` — every non-private package that is not a demo):
+
+| Package                                                                                           | Directory                             |
+| ------------------------------------------------------------------------------------------------- | ------------------------------------- |
+| [`@xmachines/shared`](../api/@xmachines/shared/README.md)                                         | `packages/shared`                     |
+| [`@xmachines/play`](../api/@xmachines/play/README.md)                                             | `packages/play`                       |
+| [`@xmachines/play-actor`](../api/@xmachines/play-actor/README.md)                                 | `packages/play-actor`                 |
+| [`@xmachines/play-signals`](../api/@xmachines/play-signals/README.md)                             | `packages/play-signals`               |
+| [`@xmachines/play-router`](../api/@xmachines/play-router/README.md)                               | `packages/play-router`                |
+| [`@xmachines/play-dom`](../api/@xmachines/play-dom/README.md)                                     | `packages/play-dom`                   |
+| [`@xmachines/play-dom-router`](../api/@xmachines/play-dom-router/README.md)                       | `packages/play-dom-router`            |
+| [`@xmachines/play-react`](../api/@xmachines/play-react/README.md)                                 | `packages/play-react`                 |
+| [`@xmachines/play-react-router`](../api/@xmachines/play-react-router/README.md)                   | `packages/play-react-router`          |
+| [`@xmachines/play-solid`](../api/@xmachines/play-solid/README.md)                                 | `packages/play-solid`                 |
+| [`@xmachines/play-solid-router`](../api/@xmachines/play-solid-router/README.md)                   | `packages/play-solid-router`          |
+| [`@xmachines/play-svelte`](../api/@xmachines/play-svelte/README.md)                               | `packages/play-svelte`                |
+| [`@xmachines/play-sveltekit-router`](../api/@xmachines/play-sveltekit-router/README.md)           | `packages/play-sveltekit-router`      |
+| [`@xmachines/play-svelte-spa-router`](../api/@xmachines/play-svelte-spa-router/README.md)         | `packages/play-svelte-spa-router`     |
+| [`@xmachines/play-tanstack-react-router`](../api/@xmachines/play-tanstack-react-router/README.md) | `packages/play-tanstack-react-router` |
+| [`@xmachines/play-tanstack-solid-router`](../api/@xmachines/play-tanstack-solid-router/README.md) | `packages/play-tanstack-solid-router` |
+| [`@xmachines/play-vue`](../api/@xmachines/play-vue/README.md)                                     | `packages/play-vue`                   |
+| [`@xmachines/play-vue-router`](../api/@xmachines/play-vue-router/README.md)                       | `packages/play-vue-router`            |
+| [`@xmachines/play-xstate`](../api/@xmachines/play-xstate/README.md)                               | `packages/play-xstate`                |
+| [`@xmachines/docs`](../README.md)                                                                 | `packages/docs`                       |
+
+**Example demo packages** (under `packages/*/examples/demo`) are **not published** to npm (`"npmPublish": false`) but are still packed into release tarballs and attached as GitLab release assets for testing.
+
+Each published package includes only the directories listed in its `files` field: `dist`, `README.md`, and `LICENSE` (or equivalent for packages without a compilation step).
+
+---
+
+## Build Pipeline
+
+### CI Pipeline Stages
+
+Pipeline runs are triggered by `.gitlab-ci.yml` under the following conditions:
+
+| Trigger                                          | Pipeline runs                                      |
+| ------------------------------------------------ | -------------------------------------------------- |
+| Push to `main` / `rc` / `beta` / `alpha` / `pre` | Full pipeline; the release job waits to be started |
+| Merge request                                    | Full pipeline, no release job                      |
+| Web / API / trigger / parent pipeline            | Full pipeline                                      |
+
+No rule admits a tag pipeline, so pushing a tag runs nothing.
+
+The pipeline includes two reusable CI components, both pinned in `.gitlab-ci.yml` — which is the version to trust, rather than a number repeated here:
+
+- **`to-be-continuous/node/gitlab-ci-node`** — handles install, lint, build, test, and audit
+- **`to-be-continuous/semantic-release/gitlab-ci-semrel`** — runs `semantic-release` on eligible branches
+
+The `node-build` job runs with:
+
+```bash
+pnpm run build           # tsc --build (TypeScript composite build)
+pnpm run test:coverage   # vitest run --coverage (with JUnit + Cobertura reporters)
+```
+
+Coverage is extracted from the `node-build` job via the regex:
+
+```
+/All files[^|]*\|[^|]*\s+([\d\.]+)/
+```
+
+JUnit results are published as `reports/junit.xml` and Cobertura coverage as `reports/coverage/cobertura-coverage.xml`.
+
+### Release Job Detail
+
+The `semantic-release` CI job is configured with:
+
+```yaml
+semantic-release:
+    id_tokens:
+        NPM_ID_TOKEN:
+            aud: "npm:registry.npmjs.org"
+    artifacts:
+        when: always
+        expire_in: 1 week
+        paths:
+            - dist/releases/*.tgz
+```
+
+The job uses a GitLab OIDC id token (`NPM_ID_TOKEN`) scoped to `npm:registry.npmjs.org` rather than a static `NPM_TOKEN`.
+
+The `semantic-release` command is called with `--no-ci` to allow it to run inside CI without triggering its own CI-environment mode.
+
+### Release Smoke Test Job
+
+The `release-pack-smoke` job is defined in `.gitlab-ci.yml` and runs on the same trigger rules as other CI jobs (automatically on `main` pushes and tags, manually on MRs):
+
+```bash
+pnpm run build
+node scripts/release-pack-smoke.mjs
+```
+
+`scripts/release-pack-smoke.mjs`:
+
+1. Reads `release.config.mjs` to find all `@semantic-release/npm` plugin entries where `npmPublish` is not `false`.
+2. For each publishable package: runs `npm pack --json` in the package directory.
+3. Creates a temporary directory, runs `npm init -y`, and installs the local tarball with `--ignore-scripts`.
+4. Asserts the install succeeds — any missing files, broken exports, or pack-time errors surface here.
+5. Cleans up temp directories and tarballs after each check.
+
+This smoke test runs **before** the actual publish so packaging problems are caught in CI rather than on npm.
+
+---
+
+## Semantic Release Process
+
+### Branch Model
+
+Releases are driven by commit history on the release branches:
+
+| Branch  | Channel          | Tag format       | Behaviour                     |
+| ------- | ---------------- | ---------------- | ----------------------------- |
+| `main`  | stable (default) | `v1.2.3`         | Full production release       |
+| `rc`    | `rc`             | `v1.2.3-rc.N`    | Release candidate pre-release |
+| `beta`  | `beta`           | `v1.2.3-beta.N`  | Beta pre-release              |
+| `alpha` | `alpha`          | `v1.2.3-alpha.N` | Alpha pre-release             |
+| `pre`   | `pre`            | `v1.2.3-pre.N`   | Pre-release                   |
+
+The channel becomes the npm dist-tag verbatim, which is why none of them contains a slash: npm reads a slash in a version selector as a GitHub shorthand, so such a tag cannot be installed.
+
+Tag format is `v${version}` (e.g., `v1.0.0-beta.46`).
+
+### Prepare Phase
+
+Before any package is published, semantic-release runs a sequence of `@semantic-release/exec` prepare steps defined in `release.config.mjs`:
+
+```bash
+corepack enable
+pnpm install --frozen-lockfile
+node scripts/set-workspace-versions.mjs ${nextRelease.version}
+pnpm run build
+pnpm --filter @xmachines/docs run typedoc --gitRevision v${nextRelease.version}
+pnpm --filter @xmachines/docs run format
+```
+
+Step by step:
+
+1. **Enable corepack** — activates the pinned pnpm version.
+2. **Install** — `pnpm install --frozen-lockfile` installs the exact dependency versions recorded in the lockfile.
+3. **Sync versions** — `scripts/set-workspace-versions.mjs` sets the same release version across every `package.json` in the workspace (root + all packages), including cross-package workspace dependency ranges.
+4. **Build** — runs `tsc --build` to produce compiled `dist/` output in all packages.
+5. **Generate API docs** — runs TypeDoc to regenerate `packages/docs/api/` at the release git revision.
+6. **Format docs** — runs `oxfmt` on the docs package to ensure consistent formatting.
+
+### Publish Phase
+
+Each publishable package is published in sequence via individual `@semantic-release/npm` plugin entries. Each entry specifies:
+
+- `pkgRoot` — the package directory relative to the workspace root
+- `tarballDir` — `dist/releases/` where the packed `.tgz` is saved
+
+Example (from `release.config.mjs`, where these entries are generated rather than
+hand-written):
+
+```js
+["@semantic-release/npm", { pkgRoot: "packages/play", tarballDir: "dist/releases" }];
+```
+
+### Post-Release Phase
+
+After all packages are published:
+
+1. **`@semantic-release/git`** commits updated files back to the repository:
+    - `CHANGELOG.md`
+    - `package.json` and `package-lock.json` (root)
+    - `packages/*/{package.json,examples/*/package.json}` (all workspace packages)
+    - `packages/docs/api/**` (generated API documentation)
+
+    Commit message format:
+
+    ```
+    chore(release): <version>
+
+    <release notes>
+
+    [skip ci]
+    ```
+
+2. **`@semantic-release/gitlab`** creates a GitLab Release entry attached to the version tag, with all `dist/releases/*.tgz` tarballs as downloadable assets labelled "Release tarballs".
+
+3. **`@semantic-release/changelog`** updates `CHANGELOG.md` with generated release notes.
+
+---
+
+## Version Synchronisation
+
+All packages in the monorepo share a **single version** at all times. This is enforced during release by `scripts/set-workspace-versions.mjs`, which:
+
+- Sets `version` in every workspace `package.json` (including the root) to the new release version.
+- Rewrites `dependencies`, `devDependencies`, `peerDependencies`, and `optionalDependencies` ranges for any `@xmachines/*` workspace package to the exact new version (no `^` or `~` prefix — a strict pinned version is written).
+
+This means packages always depend on the exact same version of sibling packages that was released together.
+
+---
+
+## Credentials and Protected Variables
+
+| Variable                    | Source                                  | Purpose                                                                         |
+| --------------------------- | --------------------------------------- | ------------------------------------------------------------------------------- |
+| `NPM_ID_TOKEN`              | GitLab CI OIDC (auto-generated per job) | Authenticates `semantic-release` to npm registry via OIDC token exchange        |
+| `GL_TOKEN` / `GITLAB_TOKEN` | GitLab CI group variable (unprotected)  | Authenticates `@semantic-release/gitlab` for release creation and git push back |
+| `CI_JOB_TOKEN`              | GitLab CI built-in                      | Used by the `to-be-continuous` components for GitLab API calls                  |
+
+**No static npm token is committed to the repository.** The `NPM_ID_TOKEN` is a short-lived OIDC token generated for each CI job with audience `npm:registry.npmjs.org`.
+
+To publish packages, a maintainer must:
+
+1. Have push access to a release-eligible branch (`main`, `rc`, `beta`, `alpha`, `pre`). Only `main` is protected; see the branch model above for what changes if `GITLAB_TOKEN` is ever made a protected variable.
+2. Ensure the GitLab project CI/CD variables include the required tokens.
+
+---
+
+## Artifacts
+
+Release tarballs are stored as GitLab CI artifacts for **1 week** after each pipeline:
+
+```
+dist/releases/*.tgz
+```
+
+The same tarballs are attached to the GitLab Release entry as permanent downloadable assets. Tarballs are **not committed** to git (the `dist/` directory is gitignored).
+
+The API documentation (`packages/docs/api/`) **is committed** to git by the post-release git commit and is the only generated artifact tracked in version control.
+
+---
+
+## Rollback Procedure
+
+There is no automated rollback mechanism. To revert a release:
+
+1. **npm deprecate** (preferred) — deprecate the bad version on npm so it is hidden from installs:
+
+    ```bash
+    npm deprecate @xmachines/play@<bad-version> "Deprecated: use <good-version>"
+    ```
+
+    Repeat for each affected package.
+
+2. **npm unpublish** — unpublish the bad version if it was published within 72 hours and no dependents exist:
+
+    ```bash
+    npm unpublish @xmachines/play@<bad-version>
+    ```
+
+3. **Patch release** — push a `fix:` commit to `main` (or the relevant branch) to trigger a patch version release via semantic-release. This is the preferred long-term approach for production issues.
+
+4. **GitLab Release** — delete or edit the GitLab Release entry via the GitLab UI or API to remove broken tarballs. This does not affect what is on npm.
+
+---
+
+## Recovering a Failed Release
+
+If the job dies partway (e.g. one package's trusted publisher isn't set up), some packages are published, the git tag is created, and the rest are missing. To finish the release:
+
+1. **Delete the release tag.** semantic-release creates the tag _before_ publishing, so a re-run while it exists is a no-op ([semantic-release#3178](https://github.com/semantic-release/semantic-release/issues/3178)):
+    ```bash
+    glab api --method DELETE "projects/xmachin-es%2Fxmachines-js/repository/tags/vX.Y.Z"
+    ```
+2. **Re-run the `semantic-release` job.**
+
+The config detects a staged-but-untagged version (a recovery re-run) and automatically demotes any package already on npm at that version to pack-only — re-packing it for the release assets but **not** re-publishing it — so the re-run publishes only what's missing, with no manual input. `SEMREL_SKIP_STEPS` (a regex matched against release step IDs) remains available as a manual override to force-skip specific steps.
+
+> First fix the underlying cause before re-running — e.g. configure the missing trusted publisher — otherwise the same packages fail again.
+
+---
+
+## Local Release Dry-Run (Manual)
+
+To preview what semantic-release would do without publishing:
+
+```bash
+# Install dependencies first
+pnpm install --frozen-lockfile
+
+# Run semantic-release in dry-run mode
+pnpm exec semantic-release --dry-run --no-ci
+```
+
+To test package packaging locally (the same check run by `release-pack-smoke` in CI):
+
+```bash
+pnpm run build
+node scripts/release-pack-smoke.mjs
+```
+
+This packs every publishable package, installs each tarball in a temporary project, and verifies the install succeeds.
+
+To manually version and pack a single package for local inspection:
+
+```bash
+# From the repo root
+pnpm --filter @xmachines/play run build
+pnpm --filter @xmachines/play pack
+```
+
+**Do not run `npm publish` manually.** All publishing must go through semantic-release in CI to keep `CHANGELOG.md`, git tags, and npm versions in sync.
+
+---
+
+## Monitoring
+
+The project does not include application runtime monitoring (no Sentry, Datadog, or OpenTelemetry) — it is a library monorepo, not a deployed service.
+
+Post-release health checks:
+
+- **npm package availability** — verify new versions appear on `https://www.npmjs.com/package/@xmachines/<pkg>` after the pipeline completes.
+- **GitLab pipeline status** — monitor the `semantic-release` job in the GitLab CI UI for the release commit.
+- **GitLab Releases page** — confirm the release tag and tarball assets appear at `https://gitlab.com/xmachin-es/xmachines-js/-/releases`.
+- **`packages/docs/api/` commit** — confirm the post-release git commit updated API docs on the target branch.