Release Workflow

Release workflow (react-zmage)

Why this skill exists

A react-zmage release has to land in three places that drift independently:

The npm side requires an interactive OTP that only the human user can supply — which means the agent cannot drive the whole flow end-to-end. The skill exists to enforce a clean stop/resume around that human checkpoint, plus to bake in the lesser-known repo conventions (no v prefix on tags, bilingual notes structure, sandbox .tgz paths bumped in lockstep with core).

When to invoke

Strong triggers (just do it):

• "发版" / "我要发版" / "准备发版" / "release" / "publish to npm" / "ship X.Y.Z"
• "bump version and push"
• "tag a release"
• "提交推送 我要发版"

Weak triggers (consider, then judge):

• User says "commit and push" right after material changes to packages/core/src/** — they may want a release but didn't say so. Ask once: "ship a release with this, or commit-only?"
• Conversation has been around polishing public API (props, defaults, docs) — release may be the implicit next step. Don't auto-trigger; surface the option.

Skip:

• Pure internal refactor / test additions with no public-API change — release is overkill.
• User explicitly says "don't publish, just commit" or "preview only".

Pre-flight (Step 0 — before bumping anything)

Run these all and confirm they pass:

# Core unit + integration tests
pnpm --filter react-zmage test

# Public-docs contract (asserts llms.txt, README, AGENTS, types stay aligned)
pnpm --filter llms-eval run test

# i18n key parity across 7 languages — must all be equal
for lang in en de es fr ja ko zh-CN; do
  count=$(grep -cE "^[[:space:]]+'[^']+':" "packages/home/src/i18n/$lang.ts")
  echo "$lang: $count keys"
done

# Build core to verify dist artifacts produce
pnpm --filter react-zmage run build

# (Optional but strong) full sandbox check — catches dist regressions
pnpm -w run check

If sync-public-docs was triggered earlier in the conversation, or if the release includes user-facing docs / homepage / examples, also confirm:

• pnpm --filter react-zmage-home run build succeeded
• regenerated docs/index.html, docs/404.html, and docs/assets/* are included when the home bundle changed
• If docs/llms.txt changed, pnpm --filter llms-eval run test passed and docs/llms.txt is included in the commit
• the built docs bundle contains the new public examples or labels (for example, grep the latest docs/assets/*.js for the new example headings / i18n strings)
• docs/.nojekyll exists if the repo contains Markdown under docs/ that Jekyll could parse as Liquid

If anything is red, fix it before continuing. A release must be on green.

The release flow (Steps 1–9)

Step 1 — Diagnose unreleased commits and decide the version

# Find the last released tag
git tag -l --sort=-v:refname | head -3
# → 1.5.0 / 1.4.1 / 1.4.0  (no `v` prefix — repo convention)

# Enumerate everything since the last tag
git log --oneline <last-tag>..HEAD

Group commits into:

• BREAKING — explicit ! marker (e.g. refactor(core)!: rename X → Y) or any change that breaks consumer code at compile time / runtime
• feat — additive new capability
• fix — bug fix observable to consumers
• chore / refactor / test / docs — internal-only; don't mention in release notes

Semver suggestion → always confirm with the user before bumping:

Always present the choice and let the user pick. Frame it as: "Strict semver says X.Y.Z, but you've historically chosen W.V.U. Which one?"

Step 2 — Bump versions in lockstep

Core is the source of truth. Four sandbox packages pin its .tgz for integration tests — they all carry the same version string and must move together.

Files to edit (verify with grep '"react-zmage"' packages/sandbox-*/package.json first; the list may grow):

packages/core/package.json                 →  "version": "<NEW>"
packages/sandbox-r17/package.json          →  "react-zmage": "file:..\\..\\.pack\\react-zmage-<NEW>.tgz"
packages/sandbox-r18/package.json          →  same
packages/sandbox-r19/package.json          →  same
packages/sandbox-nextjs/package.json       →  same

Other workspace packages (home, llms-eval, apps/*) stay on 0.0.0 — they're private/internal and not published.

Step 3 — Build core to verify dist

pnpm --filter react-zmage run build

Must show Build success for both ESM and CJS, plus the ssr/ subentry. If tsup fails, do not proceed — the dist is what npm ships.

Step 4 — Commit (conventional format with version in subject)

Repo style (see git log --format=%s -10): the commit that ships also bumps the version. Subject line names the headline change and ends with the version in parens.

<type>(<scope>): <headline> (<X.Y.Z>)

<body — 3–5 paragraphs covering what shipped, why, and any gotchas>

<optional code example or migration note>

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Examples from repo history:

• fix(core): isolate ESC/hotkeys from outer modal listeners (1.4.1)
• feat(core): hotKey rotate / download + custom-descriptor surface (1.5.0)

Stage files explicitly (no git add -A) — see Anti-patterns. Use a HEREDOC to preserve message formatting:

git commit -m "$(cat <<'EOF'
feat(core): <headline> (<X.Y.Z>)

<body>

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
EOF
)"

Step 5 — Push to master

git push origin master

Capture the resulting commit SHA — later steps need it.

Step 5.5 — GitHub Actions and Pages gate

After pushing, inspect the workflows for the pushed commit before asking the user to publish to npm:

gh run list --commit <commit-sha> --limit 10 --json databaseId,workflowName,status,conclusion,url
gh run watch <run-id> --exit-status

At minimum, CI must pass. If Pages is triggered, it must also pass unless the release explicitly does not touch public docs or site assets. For any failed run:

gh run view <run-id> --json jobs,conclusion,status,url
gh run view <run-id> --log-failed

Fix the logged root cause locally, run the closest matching verification command, commit the fix, push again, and re-check the new workflow runs. Do not continue to npm publish while the release commit or a follow-up fix commit is still red.

If homepage examples / docs changed, verify the deployed site after Pages succeeds. Fetch https://zmage.caldis.me/ with a no-cache header, extract the current assets/*.js, and confirm it contains the expected new example labels in English and Chinese. If Pages is green but the old asset is still served, report the cache delay and retry before calling the website updated.

Step 6 — STOP. Tell the user to run npm publish themselves.

This is the hard stop. Do not run npm publish from the agent.

The npm account requires an OTP (one-time password) at publish time. Only the user can supply it interactively. Suggest the exact command and wait:

Pushed <sha> to master. Run cd packages/core && npm publish yourself (needs your OTP). Tell me when it's done and I'll handle tag + GitHub Release.

If the user offers to "let you publish" — politely decline and ask them to run it. The OTP friction is intentional security; bypassing it is not in scope.

Step 7 — After user confirms publish: tag and push it

Repo convention: bare-version tags, no v prefix. Verify with git tag -l | head — historical tags are 1.5.0, 1.4.1, 0.8.5, etc. Mismatching this breaks tools that assume monotonic naming.

git tag <X.Y.Z> <commit-sha>
git push origin <X.Y.Z>

(Lightweight tag is fine — repo history uses both. --follow-tags only pushes annotated tags, so explicit git push origin <tag> is the safe form.)