diff --git a/.opencode/skills/release-workflow/SKILL.md b/.opencode/skills/release-workflow/SKILL.md new file mode 100644 index 0000000..f92e372 --- /dev/null +++ b/.opencode/skills/release-workflow/SKILL.md @@ -0,0 +1,230 @@ +--- +name: release-workflow +description: Standard release procedure for lancedb-opencode-pro. Use when publishing a new npm version. Covers version bump, local verification, branch/PR flow, tagging, CI gate, and npm publish confirmation. +license: MIT +metadata: + author: tryweb + version: "1.0" + generatedBy: "manual" +--- + +# Release Workflow — lancedb-opencode-pro + +Use this skill when the user wants to publish a new version to npm. + +--- + +## Pre-Conditions (Check Before Starting) + +- All intended feature changes are merged to `main` +- `npm whoami` returns the publishing account (run on host, not in Docker) +- `NPM_TOKEN` secret is set in GitHub Actions repository settings +- No open `fix/` branches with uncommitted work + +--- + +## Phase 1 — Local Preparation (Host) + +**Goal**: Confirm the current codebase builds and passes all tests before touching version numbers. + +```bash +# Run the full release gate inside Docker +docker compose build --no-cache && docker compose up -d +docker compose exec app npm run verify:full +``` + +Gate passes when: +- typecheck exits 0 +- build exits 0 +- foundation 10/10, regression 18/18, retrieval 2/2 +- benchmark latency within thresholds +- `npm pack` produces a `.tgz` with no errors + +If the gate fails, **stop and fix root causes** before proceeding. Never bump the version on a failing codebase. + +--- + +## Phase 2 — Version & Changelog + +```bash +# On main, bump version in package.json +# Edit CHANGELOG.md — add a new ## [X.Y.Z] section at the top +``` + +Commit message format: +``` +chore: bump version to X.Y.Z and update changelog +``` + +--- + +## Phase 3 — Release Branch + +```bash +git checkout -b release/vX.Y.Z +git push origin release/vX.Y.Z +``` + +--- + +## Phase 4 — PR to Main + +```bash +gh pr create \ + --title "chore: release vX.Y.Z" \ + --body "Bump version to X.Y.Z. See CHANGELOG.md for details." \ + --base main \ + --head release/vX.Y.Z +``` + +Wait for `verify` CI check to pass, then merge: + +```bash +gh pr merge --squash --delete-branch +git checkout main && git pull origin main +``` + +--- + +## Phase 5 — Tag and Trigger CI Release + +```bash +git tag vX.Y.Z +git push origin vX.Y.Z +``` + +This triggers the `verify-full-release` GitHub Actions workflow, which: +1. Runs `npm run verify:full` inside Docker +2. Packs the `.tgz` +3. Uploads artifact +4. Publishes to npm via `NPM_TOKEN` +5. Creates GitHub Release with `.tgz` asset + +Monitor with: +```bash +gh run watch --interval 30 +``` + +Or list recent runs: +```bash +gh run list --workflow=ci.yml --limit=5 +``` + +--- + +## Phase 6 — Post-Release Verification + +```bash +# Confirm npm version is live +npm view lancedb-opencode-pro name version + +# Confirm GitHub Release exists with .tgz asset +gh release view vX.Y.Z --repo tryweb/lancedb-opencode-pro +``` + +Both must succeed before declaring the release complete. + +--- + +## Troubleshooting + +### Regression tests fail in CI but pass locally + +Root causes encountered in practice: + +1. **Sidecar config bleed**: Global `~/.config/opencode/lancedb-opencode-pro.json` overrides test config. + - Symptom: `resolveMemoryConfig` tests fail with "Missing expected exception" + - Fix: Use `LANCEDB_OPENCODE_PRO_SKIP_SIDECAR=true` in test `withPatchedEnv` + +2. **LanceDB eventual consistency**: `hasMemory()` can't see a record immediately after `put()`. + - Symptom: `memory_feedback_wrong` returns "not found in current scope" even though `memory_search` finds it + - Fix: Retry loop in `hasMemory()` (3× at 50ms intervals) + +3. **ENOTEMPTY on cleanup**: LanceDB holds file handles when `rm -rf` runs. + - Symptom: `ENOTEMPTY: directory not empty, rmdir ...` in test teardown + - Fix: 50ms delay + one retry in `cleanupDbPath()` + +4. **`hooks.config()` called outside env patch**: Causes `state.config.dbPath` to be reset to global sidecar path. + - Symptom: `memory_stats` shows `~/.opencode/memory/lancedb` instead of test dbPath + - Fix: Never call `hooks.config()` outside `withPatchedEnv` + +### CI failed, tag already pushed + +```bash +# Fix root cause, merge fix to main, then: +git tag -d vX.Y.Z +git push origin :refs/tags/vX.Y.Z + +git tag vX.Y.Z +git push origin vX.Y.Z +``` + +### npm publish fails with EACCES on dist/ + +Some build artifacts were created by root inside Docker: + +```bash +docker compose up -d +docker compose exec -T -u root app sh -lc \ + 'chown -R 1000:1000 /workspace/dist /workspace/dist-test 2>/dev/null || true' +npm publish +``` + +### Branch protection blocks direct push to main + +Branch protection requires PR + `verify` status check. Always use a branch + PR flow. +If you temporarily disabled protection to hotfix, restore it after: + +```bash +gh api repos/tryweb/lancedb-opencode-pro/branches/main/protection \ + --method PUT \ + --header "Accept: application/vnd.github+json" \ + --input - <<'EOF' +{ + "required_status_checks": { "strict": false, "contexts": ["verify"] }, + "enforce_admins": true, + "required_pull_request_reviews": { + "dismiss_stale_reviews": true, + "require_code_owner_reviews": false, + "required_approving_review_count": 0 + }, + "restrictions": null, + "required_conversation_resolution": true, + "allow_force_pushes": false, + "allow_deletions": false +} +EOF +``` + +--- + +## Quick Reference — All Commands + +```bash +# Phase 1 — local gate +docker compose build --no-cache && docker compose up -d +docker compose exec app npm run verify:full + +# Phase 2 — version bump +# Edit package.json + CHANGELOG.md, then: +git add package.json CHANGELOG.md +git commit -m "chore: bump version to X.Y.Z and update changelog" + +# Phase 3 — release branch +git checkout -b release/vX.Y.Z +git push origin release/vX.Y.Z + +# Phase 4 — PR + merge +gh pr create --title "chore: release vX.Y.Z" --base main --head release/vX.Y.Z +gh pr merge --squash --delete-branch +git checkout main && git pull origin main + +# Phase 5 — tag +git tag vX.Y.Z HEAD +git push origin vX.Y.Z +gh run list --workflow=ci.yml --limit=3 + +# Phase 6 — verify +npm view lancedb-opencode-pro version +gh release view vX.Y.Z --repo tryweb/lancedb-opencode-pro +```