wehub-resource-sync
327 lines
16 KiB
Markdown
327 lines
16 KiB
Markdown
---
|
|
title: "Release Checklist"
|
|
version: 3.8.40
|
|
lastUpdated: 2026-06-28
|
|
---
|
|
|
|
# Release Checklist
|
|
|
|
> **Last updated:** 2026-06-28 — v3.8.40
|
|
> Streamlined release flow that leverages Claude Code skills for automation.
|
|
>
|
|
> **Keep the queue/branch green between releases:** see [RELEASE_GREEN.md](./RELEASE_GREEN.md)
|
|
> (`/green-prs` family + `npm run check:release-green` + `/babysit` + nightly). Running
|
|
> this periodically — and especially **before** this checklist — makes the release PR start green.
|
|
|
|
## TL;DR
|
|
|
|
```bash
|
|
# 1. Bump version + generate CHANGELOG (skill)
|
|
/version-bump-cc patch # or minor/major
|
|
|
|
# 2. Run quality gate locally
|
|
npm run check # lint + tests
|
|
npm run test:coverage # full coverage gate (60/60/60/60)
|
|
|
|
# 3. Build & smoke
|
|
npm run build
|
|
npm run test:e2e # optional but recommended
|
|
|
|
# 4. Generate release (skill)
|
|
/generate-release-cc
|
|
|
|
# 5. Deploy (skill)
|
|
/deploy-vps-both-cc # or akamai-cc / local-cc
|
|
|
|
# 6. Capture release evidences (skill)
|
|
/capture-release-evidences-cc
|
|
```
|
|
|
|
## Detailed Checklist
|
|
|
|
### Pre-release
|
|
|
|
- [ ] All PRs targeted to this release are merged to `release/vX.Y.0`
|
|
- [ ] All open Linear/issue items for this version are closed or pushed to next milestone
|
|
- [ ] CI green on `release/vX.Y.0` branch
|
|
- [ ] No `TODO(release)` markers in code: `grep -r "TODO(release)" src/ open-sse/`
|
|
- [ ] Docker base image up to date (currently `node:24.15.0-trixie-slim`)
|
|
|
|
### Version & Changelog
|
|
|
|
- [ ] Run `/version-bump-cc <patch|minor|major>` (Claude Code skill)
|
|
- Bumps `package.json`, `electron/package.json`
|
|
- Regenerates `CHANGELOG.md` from git commits since last tag
|
|
- Updates README.md badges
|
|
- [ ] Manually review CHANGELOG.md and clean up commit messages if needed
|
|
- [ ] Ensure the latest semver section in `CHANGELOG.md` equals `package.json` version
|
|
- [ ] Keep `## [Unreleased]` as the first changelog section for upcoming work
|
|
- [ ] Update `docs/openapi.yaml` → `info.version` must equal `package.json` version
|
|
|
|
### Code Quality
|
|
|
|
- [ ] `npm run lint` — 0 errors (warnings are pre-existing)
|
|
- [ ] `npm run typecheck:core` — clean
|
|
- [ ] `npm run typecheck:noimplicit:core` — clean (strict)
|
|
- [ ] `npm run check:cycles` — no circular deps
|
|
- [ ] `npm run check:any-budget:t11` — within budget
|
|
- [ ] `npm run check:route-validation:t06` — clean
|
|
- [ ] `npm run check:node-runtime` — supported runtime floor met (`>=22.22.2 <23`, `>=24.0.0 <27`, per `SUPPORTED_NODE_RANGE` in `src/shared/utils/nodeRuntimeSupport.ts`; aligned with `package.json` `engines`)
|
|
|
|
### Testing
|
|
|
|
- [ ] `npm run test:unit` — pass
|
|
- [ ] `npm run test:vitest` — pass (MCP server, autoCombo, cache)
|
|
- [ ] `npm run test:coverage` — gate 60/60/60/60 satisfied (statements/lines/functions/branches)
|
|
- [ ] `npm run test:integration` — pass (if changes touch DB / handlers)
|
|
- [ ] `npm run test:combo:matrix` — pass (combo strategy matrix: proves all 17 routing strategies' selection decisions deterministically; run when touching combo routing, strategy resolution, or fallback logic)
|
|
- [ ] `RUN_COMBO_LIVE=1 npm run test:combo:live` — **optional/manual** (gated real-upstream smoke; sources a read-only DB snapshot from VPS `root@192.168.0.15`; hits real providers, costs credits; never runs in CI; skips cleanly without the gate)
|
|
- [ ] `npm run test:combo:live:vps` — **optional/manual** (Phase-3 VPS live smoke: 7 HTTP scenarios against the live `.15` server via plain Node ESM; requires `ssh root@192.168.0.15`; creates/deletes only `__live_test__*` combos; hits real providers; never runs in CI)
|
|
- [ ] `npm run test:e2e` — pass (UI changes)
|
|
- [ ] `npm run test:protocols:e2e` — pass (MCP/A2A changes)
|
|
- [ ] `npm run test:ecosystem` — pass
|
|
|
|
### Hooks (Husky validated)
|
|
|
|
Husky hooks live in `.husky/` and run automatically on git operations.
|
|
|
|
- **pre-commit:** `npx lint-staged + node scripts/check/check-docs-sync.mjs + npm run check:any-budget:t11`
|
|
- **pre-push:** fast deterministic gates — `npm run check:any-budget:t11 && npm run check:tracked-artifacts` (activated 2026-06-13). Intentionally excludes `test:unit` (slow; covered by the CI `test-unit` job).
|
|
- Run `npm run test:unit` manually before pushing release branches.
|
|
|
|
If a hook fails: fix the underlying issue, don't bypass with `--no-verify`.
|
|
|
|
### Conventional Commits
|
|
|
|
All release-bound commits must follow `type(scope): subject` format.
|
|
|
|
**Valid types:** `feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `perf`, `style`, `ci`
|
|
|
|
**Valid scopes:** `db`, `sse`, `oauth`, `dashboard`, `api`, `cli`, `docker`, `ci`, `mcp`, `a2a`, `memory`, `skills`, `cloud-agent`, `guardrails`, `compression`, `auto-combo`, `resilience`, `providers`, `executors`, `translator`, `domain`, `authz`
|
|
|
|
Breaking changes: add `BREAKING CHANGE:` footer or `!` after the scope (e.g. `feat(api)!: drop /v0`).
|
|
|
|
### Documentation
|
|
|
|
- [ ] `npm run check:docs-sync` passes (auto-run by pre-commit)
|
|
- [ ] `npm run check:docs-all` passes (umbrella: docs-sync + docs-counts + env-doc-sync + deprecated-versions + doc-links)
|
|
- [ ] `npm run check:env-doc-sync` exits 0 — code ↔ `.env.example` ↔ `docs/reference/ENVIRONMENT.md` env contract is intact
|
|
- [ ] `npm run check:doc-links` exits 0 — no broken internal markdown references after restructuring
|
|
- [ ] `docs/architecture/ARCHITECTURE.md` reviewed for storage/runtime drift
|
|
- [ ] `docs/guides/TROUBLESHOOTING.md` reviewed for env var and operational drift
|
|
- [ ] If `.env.example` changed: `docs/reference/ENVIRONMENT.md` updated
|
|
- [ ] If new feature has a UI: `docs/guides/USER_GUIDE.md` mentions it
|
|
- [ ] If new feature has API: `docs/reference/API_REFERENCE.md` + `docs/openapi.yaml` updated
|
|
- [ ] If new feature is a module: dedicated `docs/<MODULE>.md` exists
|
|
- [ ] If breaking change: `docs/guides/TROUBLESHOOTING.md` has migration note
|
|
|
|
### i18n
|
|
|
|
- [ ] `npm run i18n:check` exits 0 — translation state (`.i18n-state.json`) in sync with source docs (no drifted sources in strict mode; warn-mode advisory is acceptable for last-minute doc touch-ups, but should be 0 before tagging)
|
|
- [ ] `npm run i18n:check-ui-coverage` exits 0 — every UI locale at or above the 80% coverage floor
|
|
- [ ] `npm run i18n:sync-ui:dry` reports 0 missing keys across all 42 locales
|
|
- [ ] If source English docs changed, run `npm run i18n:run` (requires `OMNIROUTE_TRANSLATION_API_KEY` in `.env`) before tagging
|
|
- [ ] Translation contributions can be deferred to next release if minor (track in CHANGELOG)
|
|
|
|
### Database Migrations
|
|
|
|
- [ ] If `src/lib/db/migrations/` has new files:
|
|
- [ ] Each migration is idempotent (`CREATE TABLE IF NOT EXISTS`, etc.)
|
|
- [ ] Migrations wrapped in transactions
|
|
- [ ] Numbered correctly (no gaps in sequence)
|
|
- [ ] Test on fresh install: delete `~/.omniroute/omniroute.db` and run `npm run dev`
|
|
- [ ] Test on existing install: backup DB, run migration, verify schema
|
|
- [ ] WAL files (`-wal`, `-shm`) handled correctly if migration rewrites tables
|
|
|
|
### Provider Catalog (Zod-validated)
|
|
|
|
- [ ] `src/shared/constants/providers.ts` Zod schema valid at load time
|
|
- [ ] All providers have required fields (`id`, `label`, `kind`, etc.)
|
|
- [ ] `freeNote` provided for new free providers
|
|
- [ ] OAuth providers have `oauthConfig` registered in `src/lib/oauth/constants/oauth.ts`
|
|
- [ ] If new provider added: corresponding executor in `open-sse/executors/`
|
|
- [ ] If non-OpenAI format: translator in `open-sse/translator/`
|
|
- [ ] Models registered in `open-sse/config/providerRegistry.ts`
|
|
- [ ] Unit tests in `tests/unit/` cover provider classification and routing
|
|
|
|
### Desktop (Electron)
|
|
|
|
If `electron/` changed:
|
|
|
|
- [ ] `npm run electron:smoke:packaged` passes
|
|
- [ ] Builds tested for at least one of `:win`, `:mac`, `:linux`
|
|
- [ ] Code signing certs not expired (if signing)
|
|
- [ ] `electron/package.json` version matches root `package.json`
|
|
- [ ] Auto-update channel pointer updated if releasing to `stable`
|
|
|
|
### Build Layout
|
|
|
|
The repository uses three distinct output directories — never mix them up:
|
|
|
|
| Directory | Purpose | Tracked? |
|
|
| --------- | -------------------------------------------------------- | --------------- |
|
|
| `src/` | Application source (TypeScript / TSX) | Yes |
|
|
| `.build/` | Build intermediates — `next build` output (`distDir`) | No (gitignored) |
|
|
| `dist/` | Shippable npm bundle — assembled by `assembleStandalone` | No (gitignored) |
|
|
|
|
> **Operator note:** the remote VPS image directory remains `/usr/lib/node_modules/omniroute/app/`.
|
|
> Only the **in-repo** build output moved (`app/` → `dist/`). The deploy skills rsync
|
|
> `dist/` contents into the remote `app/` dir — no VPS path changes required.
|
|
|
|
**Single-build flow:**
|
|
|
|
```
|
|
npm run build:release
|
|
└─ rm -rf .build dist (clean)
|
|
└─ next build → .build/next/ (intermediates)
|
|
└─ assembleStandalone (copies standalone + static + public + natives → dist/)
|
|
└─ writes dist/BUILD_SHA (HEAD sentinel)
|
|
```
|
|
|
|
Do NOT run `npm run build` followed by a separate `npm run build:cli` for deploy — use
|
|
`npm run build:release` which does a clean rebuild + sentinel in one command.
|
|
|
|
### Artifact Validation
|
|
|
|
- [ ] `npm run build:release` succeeds and `dist/BUILD_SHA` == `git rev-parse --short HEAD`
|
|
- [ ] `npm run check:pack-artifact` clean — no `app.__qa_backup`, `scripts/scratch`, `package-lock.json`, or other local residue
|
|
- [ ] `dist/server.js` exists after build
|
|
|
|
### Tagging & Release
|
|
|
|
- [ ] Run `/generate-release-cc` (Claude Code skill):
|
|
- Creates tag `vX.Y.Z`
|
|
- Pushes tag and branch
|
|
- Opens GitHub Release with changelog body
|
|
- Attaches Electron installers (if built)
|
|
- [ ] Or manually:
|
|
```bash
|
|
git tag -a vX.Y.Z -m "Release vX.Y.Z"
|
|
git push origin vX.Y.Z
|
|
gh release create vX.Y.Z --notes-from-tag
|
|
```
|
|
|
|
### Deploy
|
|
|
|
Deploy skills use the light rsync flow — no `npm pack`, no `npm i -g`:
|
|
|
|
- [ ] Use deploy skill that matches target:
|
|
- `/deploy-vps-local-cc` — local VPS (192.168.0.15)
|
|
- `/deploy-vps-akamai-cc` — Akamai VPS (69.164.221.35)
|
|
- `/deploy-vps-both-cc` — both
|
|
- [ ] Before deploying, confirm `dist/BUILD_SHA` == `git rev-parse --short HEAD`
|
|
- [ ] Build must run where `node_modules` is real (main checkout or `npm ci`'d worktree — NOT a symlinked worktree)
|
|
- [ ] Smoke test deployed instance:
|
|
- Open `/dashboard/health` → check version string matches release
|
|
- Run a `/v1/chat/completions` request against a known provider
|
|
- Verify `/api/monitoring/health` returns `CLOSED` circuit breakers
|
|
- Confirm MCP transports respond (`/mcp` HTTP, `/mcp-sse` SSE)
|
|
|
|
### Post-release
|
|
|
|
- [ ] Run `/capture-release-evidences-cc` (Claude Code skill)
|
|
- Captures WebP screenshots/recordings of new features
|
|
- Attaches to release notes / blog post
|
|
- [ ] Update GitHub Discussions / Discord with release announcement
|
|
- [ ] Open milestone for next version
|
|
- [ ] If critical: pin discussion or post in `news.json` for in-app banner
|
|
|
|
## Embedded Services smoke (v3.8.4+)
|
|
|
|
Before shipping any release that includes embedded services changes, verify:
|
|
|
|
### Fresh-DB boot (catches migration collisions — added after v3.8.4 hotfix)
|
|
|
|
- [ ] `DATA_DIR=$(mktemp -d) npm start &` — wait 10 s for boot
|
|
- [ ] `curl -s http://127.0.0.1:20128/api/services/9router/status | jq '.tool'` returns `"9router"` (NOT 404, NOT 500). Confirms migration `071_services.sql` applied + row seeded.
|
|
- [ ] `sqlite3 $DATA_DIR/storage.sqlite "PRAGMA table_info(version_manager);" | grep -E "provider_expose|logs_buffer_path|last_sync_at"` returns 3 rows.
|
|
- [ ] `sqlite3 $DATA_DIR/storage.sqlite "PRAGMA table_info(webhooks);" | grep -E "kind|metadata_encrypted"` returns 2 rows (validates `070_webhooks_kind_metadata.sql` applied).
|
|
- [ ] `node --import tsx/esm --test tests/unit/db/no-migration-collisions.test.ts` passes — guards against future collisions.
|
|
|
|
### 9Router
|
|
|
|
- [ ] `POST /api/services/9router/install` returns 200 with `installedVersion` in under 2 min
|
|
- [ ] `POST /api/services/9router/start` returns 200 and `state: "running"` in under 30 s
|
|
- [ ] `GET /api/services/9router/status` reports `health: "healthy"`
|
|
- [ ] `POST /v1/chat/completions` with `"model": "9router/auto/..."` returns 200 (end-to-end routing through 9Router)
|
|
- [ ] `GET /dashboard/providers/services/9router/embed/dashboard` renders the 9Router native UI inside the proxy (no direct `127.0.0.1:port` iframe)
|
|
- [ ] `POST /api/services/9router/rotate-key` returns `{ keyRotated: true }` and service restarts cleanly
|
|
- [ ] `POST /api/services/9router/stop` returns 200 and `state: "stopped"`
|
|
- [ ] `GET /api/services/9router/logs?tail=50` returns SSE stream with `snapshot` event containing recent lines
|
|
- [ ] Install in environment without `npm` in PATH returns 500 with a friendly (non-stack-trace) error message
|
|
|
|
### CLIProxyAPI
|
|
|
|
- [ ] `POST /api/services/cliproxy/install` returns 200 in under 2 min
|
|
- [ ] `POST /api/services/cliproxy/start` returns 200 and `state: "running"` in under 30 s
|
|
- [ ] `GET /api/services/cliproxy/status` reports `health: "healthy"`
|
|
- [ ] `POST /api/services/cliproxy/stop` returns 200 and `state: "stopped"`
|
|
- [ ] `GET /api/services/cliproxy/logs?tail=50` returns SSE stream
|
|
|
|
### Security regression
|
|
|
|
- [ ] `curl -H "X-Forwarded-For: 1.2.3.4" http://localhost:20128/api/services/9router/start` returns `403 LOCAL_ONLY`
|
|
- [ ] `curl -H "X-Forwarded-For: 1.2.3.4" http://localhost:20128/api/services/cliproxy/start` returns `403 LOCAL_ONLY`
|
|
- [ ] Error responses from `/api/services/*` do not contain `err.stack` or absolute file paths
|
|
|
|
## v3.8.0+ checks
|
|
|
|
Before shipping any v3.8.x release, verify these additional items:
|
|
|
|
- [ ] `omniroute --tray` boots on macOS (systray2 installed into `~/.omniroute/runtime/`)
|
|
- [ ] `omniroute --tray` boots on Linux (requires DISPLAY; graceful error if not set)
|
|
- [ ] `omniroute --tray` boots on Windows (PowerShell NotifyIcon, no extra binaries)
|
|
- [ ] `omniroute config tray enable` creates autostart entry; disable removes it
|
|
- [ ] `npm install -g omniroute@<this-version>` runs postinstall without fatal exit
|
|
- [ ] Update path keeps optional deps: `omniroute update --apply` and the auto-updater
|
|
run `npm install -g … --include=optional` so `optionalDependencies` (better-sqlite3,
|
|
keytar, tls-client, and the llmlingua SLM stack: `@atjsh/llmlingua-2`,
|
|
`@huggingface/transformers@3.5.2`, `@tensorflow/tfjs`, `js-tiktoken`) survive an update.
|
|
`@huggingface/transformers` stays optional so its `onnxruntime-node` CUDA provider postinstall
|
|
cannot abort installation on CUDA 11 hosts. The ultra `modelPath` SLM tier also needs the
|
|
tinybert model, auto-downloaded to `${DATA_DIR}/models/llmlingua` on first use. Postinstall
|
|
(`scripts/build/colocateOptionals.mjs`) then co-locates the SLM optional closure into
|
|
`dist/node_modules` so the worker resolves a SINGLE `@huggingface/transformers` 3.5.2
|
|
optional instance — the standalone trace bundles only transformers, not the dynamically-imported
|
|
optionals, so without this the worker would load llmlingua-2 against the root's transformers
|
|
and the SLM tier would silently fail-open.
|
|
- [ ] `omniroute status` works with no `.env` (CLI token path, loopback only)
|
|
- [ ] `curl http://localhost:20128/api/shutdown` returns 401 (always-protected route)
|
|
- [ ] `curl -H "host: evil.com" http://localhost:20128/api/mcp/sse` returns 401 (loopback guard)
|
|
- [ ] SQLite runtime resolves to `bundled` on first run (bundled binary valid for platform)
|
|
- [ ] SQLite runtime falls back to `runtime` when `node_modules/better-sqlite3` is deleted
|
|
- [ ] Smart MCP filter compresses real `playwright-mcp browser_snapshot` output (≥50% reduction)
|
|
- [ ] All 10 `skills/omniroute*/SKILL.md` files are publicly fetchable via raw GitHub URL
|
|
- [ ] Onboarding wizard shows "How It Works" tier tour step on fresh setup
|
|
- [ ] Home dashboard tier coverage widget shows configured/active counts
|
|
|
|
---
|
|
|
|
## Rollback
|
|
|
|
If release has critical issue:
|
|
|
|
1. `gh release edit vX.Y.Z --prerelease` (marks as not latest)
|
|
2. `git tag -d vX.Y.Z && git push --delete origin vX.Y.Z` (only if not yet adopted by users)
|
|
3. Or: hotfix on `release/vX.Y.0` → patch release `vX.Y.(Z+1)`
|
|
4. Communicate in GitHub Discussions and Discord immediately
|
|
|
|
## Hard Rules
|
|
|
|
- Never commit directly to `main`
|
|
- Never use `git push --force` to `main` or `release/*` branches
|
|
- Never skip Husky hooks (`--no-verify`)
|
|
- Never commit secrets, credentials, or `.env` files
|
|
- Coverage must stay ≥60/60/60/60 (statements/lines/functions/branches)
|
|
- Always include or update tests when changing production code in `src/`, `open-sse/`, `electron/`, or `bin/`
|
|
|
|
## Automated Sync Check
|
|
|
|
Run the docs sync guard locally before opening a PR:
|
|
|
|
```bash
|
|
npm run check:docs-sync
|
|
```
|
|
|
|
CI also runs this check in `.github/workflows/ci.yml` (lint job).
|