Skip to content

v0.22.x-housekeeping — Maintainer Runbook

Operational checklist for the org-side steps of the v0.22.x-housekeeping series. The versioned PRs (authored against the engine repo) handle the code side; this runbook covers what you do at the GitHub-org and registry level, and the order it has to happen in. Governed by ADR-068 (topology + naming) and ADR-064 (extraction safety); sequenced by decisions/roadmaps/future/repo-extraction-programme.md.

How releases split: you vs. the engine PR

Each v0.22.x release is a pair: - Org action (you, this runbook): create/rename repos, seed history, set secrets, publish. - Engine PR (authored for you, reviewed by you): the in-repo code change — URL updates, repointing, or the carve-out removal.

For the extraction releases (v0.22.4–.6) the order is strict: seed the new repo first, verify it, only then merge the engine PR that deletes the content. Never delete from the engine repo until the content lives elsewhere (ADR-064).

Global safety rules

  1. Never delete before the content lives elsewhere. Seed → verify → then the removal PR.
  2. History-preserving moves only (git filter-repo), never a flat copy.
  3. Frozen identities (ADR-036/039): CLI rac, import rac, server lore stay frozen. The PyPI distribution renames requirements-as-code → rac-core (ADR-092 lifts that one freeze; a transitional shim keeps old installs working).
  4. After each engine PR merges, the corpus gates stay green (decided validate decisions/, decided relationships decisions/ --validate, decided gate decisions/).

One-time prerequisites (decide + create before the releases that need them)

What Decision / action Needed by
Marketplace publisher id Decide rac vs lore/itsthelore (it's baked into the extension's identity/URL and matches package.json publisher). Create the publisher via an Azure DevOps org. v0.22.5
VSCE_PAT Azure DevOps PAT, scope Marketplace → Manage; add as a secret in lore-vscode. v0.22.5
OpenVSX namespace Create the namespace = publisher on open-vsx.org (Eclipse account), sign the publisher agreement; generate a token → OVSX_PAT secret in lore-vscode. v0.22.5
npm scope Create/confirm the npm org/scope @itsthelore; generate an automation token → NPM_TOKEN secret in rac-sdk-ts. v0.22.3

Update (rac-editors-buildout): the extension now lives in rac-editors (ADR-092), so the VSCE_PAT / OVSX_PAT secrets land there, not in the archived lore-vscode. See decisions/roadmaps/rac-editors-buildout.md.

Install git-filter-repo locally (pip install git-filter-repo).

Per-release steps

v0.22.1 — Rename the viewer (lore-web/ → rac-localview/)

No org action. Pure in-repo rename. Just review + merge the engine PR. (Done.)

v0.22.2 — rac-core identity

  1. Rename the GitHub repo: requirements-as-code → Settings → Repository name → rac-core. GitHub auto-redirects old clone URLs and uses: paths for ~a year, so nothing breaks immediately.
  2. Merge the engine PR that updates the ~20 in-repo URLs (pyproject, mkdocs, README badges, SARIF informationUri, docs cross-links, server.json).
  3. Sanity: the docs site rebuilds at the new Pages URL; PyPI/CLI unaffected.

v0.22.3 — Publish the TS SDK to npm (rac-sdk-ts foundation)

  1. Ensure the npm scope + NPM_TOKEN prerequisite is done.
  2. Merge the engine PR that makes @decisions/sdk publishable (scoped name @asdecided/sdk, publishConfig, sdk-v* workflow).
  3. Publish: push tag sdk-v0.1.0 → the workflow publishes to npm. Verify the package resolves: npm view @asdecided/sdk. (Do this before v0.22.5, which repoints the extension to the published SDK.)

v0.22.4 — Extract decisiongrounding (cleanest; do first)

  1. Create the empty repo itsthelore/decisiongrounding.
  2. Seed with history: bash git clone <rac-core-url> dg && cd dg git filter-repo --path decisiongrounding/ --path-rename decisiongrounding/: git remote add origin <decisiongrounding-url> && git push -u origin main
  3. Verify the new repo builds/tests on its own.
  4. Then merge the engine PR that removes decisiongrounding/ and updates references.

v0.22.5 — Extract the TS stack

  1. Confirm the SDK is already published (v0.22.3) and the Marketplace/OpenVSX prerequisites are done.
  2. Create asdecided/editors and asdecided/sdk.
  3. Seed each with history: bash # rac-sdk-ts git clone <rac-core-url> sdk && cd sdk git filter-repo --path typescript/rac-sdk/ --path-rename typescript/rac-sdk/: git remote add origin <rac-sdk-ts-url> && git push -u origin main # lore-vscode git clone <rac-core-url> ext && cd ext git filter-repo --path typescript/rac-vscode/ --path-rename typescript/rac-vscode/: git remote add origin <lore-vscode-url> && git push -u origin main
  4. In lore-vscode, repoint package.json from "@decisions/sdk": "file:../rac-sdk" to the published "@asdecided/sdk": "^<version>"; move extension-release.yml; add VSCE_PAT + OVSX_PAT secrets.
  5. Then merge the engine PR that removes typescript/ and its workflows.
  6. Publish the extension: push tag vscode-v0.1.0 in lore-vscode → Marketplace + OpenVSX. (Same VSIX serves VS Code and Cursor.)

v0.22.6 — Split + rebrand the actions (LAST — consumer-breaking)

  1. Create itsthelore/lore-watchkeeper and itsthelore/lore-gatekeeper.
  2. Seed with history: bash # lore-watchkeeper (the root action.yml) git clone <rac-core-url> wk && cd wk git filter-repo --path action.yml --path-rename action.yml:action.yml git remote add origin <lore-watchkeeper-url> && git push -u origin main # lore-gatekeeper (the pr-gate action = decided gate) git clone <rac-core-url> gk && cd gk git filter-repo --path pr-gate-action/ --path-rename pr-gate-action/: git remote add origin <lore-gatekeeper-url> && git push -u origin main
  3. In each, finalise action.yml (name/branding), add a README documenting the new uses: path, and tag v1.
  4. Then merge the engine PR that: repoints this repo's dogfood jobs (uses: ./ → …/lore-watchkeeper@v1; uses: ./pr-gate-action → …/lore-gatekeeper@v1); removes the root action.yml, validate-action/, and pr-gate-action/; and leaves a deprecation note for the old …/requirements-as-code/validate-action@<ref> path.
  5. Announce the uses: cutover for any external consumers (this is the one genuinely breaking change for third parties).

Dependency order (quick reference)

prereqs (publisher, npm scope, secrets)
  → v0.22.1 (merge)          # viewer rename, no org action
  → v0.22.2 (repo rename + merge)
  → v0.22.3 (npm publish)     # must precede v0.22.5
  → v0.22.4 (seed + merge)    # cleanest, no consumer impact
  → v0.22.5 (seed + register + publish + merge)
  → v0.22.6 (seed + tag + merge)   # last; breaks old `uses:` paths

Per-step verification

  • After every engine PR: the corpus gates (validate / relationships --validate / review / gate) and the agent-rules --check job stay green.
  • After each extraction: the new repo builds/tests standalone; nothing in rac-core references the moved path (grep for the old dir/uses: path).
  • After each publish: the artifact resolves from its registry (npm view …, the Marketplace/OpenVSX listing, the action @v1 tag).