# Release > Orchestrate an Open Notebook release — changelog audit, risk-based A/B/C test matrix, Docker image gate (fresh + upgrade), fix loop via PRs, cut, publication with credits, retro. Use when preparing, testing, cutting or publishing a release. - Skill: `lfnovo/release` (Agent Skill, multi-file: 18 files) - Install (CLI): `npx skillmds@latest add lfnovo/release` - Raw SKILL.md: https://api.skillmd.com/api/skills/lfnovo/release/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: DevOps & Infra, Coding & Dev Tools, Security - Author: lfnovo (https://skillmd.com/u/lfnovo) - Updated: 2026-09-10 - Page: https://skillmd.com/skills/lfnovo/release --- # Open Notebook Release Orchestrator You are conducting a release of Open Notebook, reproducing the process established in v1.11.0. The **source of truth for the process** is `.github/RELEASE_PROCESS.md` — read it first. This skill adds the orchestration order, the exact commands, and the human gates. **Ground rules for the whole run:** - The release happens in a **single session**. Track phases with the task tools (TaskCreate/TaskUpdate) so the owner sees progress. - Every repo change goes through a **PR** (branch → PR → CI + cubic → merge). Never push to main. Confirm the owner authorizes you to merge your own PRs when clean; otherwise hand merges to them. - Interact in the owner's language; write code, commits and docs in English. - Read `${CLAUDE_SKILL_DIR}/gates.md` NOW — it defines what you may do autonomously and what requires an explicit GO. ## Phase 0 — Scope and changelog audit 1. `git fetch --tags` · find the last release tag and `gh release list`. 2. List everything merged since: `git log ..origin/main --oneline`. 3. Audit the CHANGELOG `[Unreleased]` section against that list. Convention: entries reference the **issue** number when one exists, the PR number otherwise. Close every gap via PR. 4. Check open Dependabot alerts (`gh api repos/{owner}/{repo}/dependabot/alerts?state=open`) — a security-themed release with open highs is incoherent. Triage them into the fix loop or document acceptance. ## Phase 1 — Risk-based test matrix Read `${CLAUDE_SKILL_DIR}/test-matrix.md` and instantiate it against the actual release diff. Classify each change: what can it break, for whom, which bucket (A/B/C) verifies it. **Refine the matrix with the owner before executing** — they decide bucket-B investments and own bucket C. ## Phase 2 — Execute bucket A Run in parallel where possible: - `uv run pytest tests/` · `ruff check .` · `uv run python -m mypy .` (all three are required CI gates since the July 2026 cleanup; mypy must exit 0) - Frontend: `npm run lint`, `npm run test`, `npm run build` (production build; a stale `node_modules` produces false build failures — `npm ci` first if so) - The **smoke-e2e agent** against the local dev stack (start it: database → api → worker → frontend; check ports are free first — another project may hold 3000/8000: identify the owner via `lsof` + process cwd, never kill blind; the frontend runs fine on `PORT=3001 npm run dev` — pass the URL to the smoke agent. Also note the dev `.env` may point at a standalone SurrealDB, not the repo-compose one) - **Dev-DB leak check**: snapshot per-table record counts (at least credentials) before and after the backend suite — a diff means a test is writing to the live database (caught 48 leaked credentials in v1.12.0) - The **targeted probes** from the matrix (legitimate-use regression checks for security changes) ## Phase 3 — Image gate + bucket C kickoff - `make docker-build-local`, then `make release-test TAG= OLD_TAG=` (pull the genuine previous tag first — see gotchas in RELEASE_PROCESS.md). - Hand the owner their bucket-C checklist (from the matrix) so they test in parallel — do not leave them as the bottleneck at the end. ## Phase 4 — Fix loop For each finding: reproduce → root-cause → focused PR with regression tests → CI + cubic → merge (per gates.md). Apply the re-test policy from RELEASE_PROCESS.md after each merge. Pre-existing bugs that are not release regressions become backlog issues (ask the owner before creating issues). Verify UI fixes in the real browser (Playwright) before opening the PR. ## Phase 5 — Cut 1. Cut PR off updated main: bump `pyproject.toml`, date the changelog section. 2. After merge: `make tag`. 3. Rebuild the image from final main and **re-run the image gate** against it. 4. Push version images via CI: `gh workflow run build-and-release.yml --ref main -f push_latest=false` and watch the run. (Local `make docker-push` needs `docker login`.) 5. Verify the pushed manifests (see `${CLAUDE_SKILL_DIR}/runbook.md`). ## Phase 6 — Pushed-image verification (human gate) Offer the owner a browsable RC stack on this machine: `make release-stack TAG= [DUMP=]` — with a copy of their dev data for realism (export command in the runbook). Support them through it; findings go back to Phase 4. **Do not proceed without their GO.** ## Phase 7 — Publish (human gate) 1. Draft release notes per `${CLAUDE_SKILL_DIR}/comms-templates.md` — the **Thanks section is mandatory**; collect every contributor with the commands in the template. Show the owner for review. 2. With their explicit GO: `gh release create v --title ... --notes-file ... --latest`. Publication triggers CI to push `v1-latest` — watch it, then verify the latest manifests (runbook). 3. Mark shipped issues with the `released` label (ask before mass-labeling). 4. Deliver the Discord post text (the owner posts it). ## Phase 8 — Cleanup `make release-stack-down`, remove temp dumps/data dirs, stop watchers, ensure `git status` is clean on main and no test containers remain. ## Phase 9 — Retro (always runs) Ask the owner: *"what should improve in this process?"* — and apply the accepted improvements **now**: edit `.github/RELEASE_PROCESS.md`, `scripts/release-test/*`, and this skill's files while context is fresh. New gotchas discovered during the run go into RELEASE_PROCESS.md's Known Gotchas via the same PR flow.