wmasfoe/md-editor / .agents/skills/release
release
VerifiedCross-platform release, version bumping, changelog maintenance, and production deployment protocol for md-editor
Multi-Platform Release & Deployment Skill
This skill guides agents through the end-to-end lifecycle for versioning, changelog generation, tagging, CI/CD pipeline monitoring, and production deployment across all client platforms in the md-editor workspace.
1. Operating Principles
- Strict Platform Symmetry: Every client platform (
desktop,web,site,utools,worker) has a clear, isolated release lifecycle and namespace. - Single Source of Truth in Git:
- NEVER build or upload binaries out-of-band without committing the version bump and changelog to the Git repository.
- Version files (
package.json,build.gradle.kts,tauri.conf.json,Cargo.toml) andCHANGELOG.md(plusCHANGELOG_EN.md) must be updated and committed together.
- Changelog-Driven Presentation:
- The official website (
site) and distribution portal read directly from each platform'sCHANGELOG.mdat build/ISR time. - A release is only complete when its user-facing changelog entry is present in both Chinese (
CHANGELOG.md) and English (CHANGELOG_EN.md).
- The official website (
- Pre-Release Quality Gate:
- Working tree must be clean.
- Must be on the latest
mainbranch. pnpm verify(lint+test+typecheck) must pass 100% before any release command is executed.
2. Multi-Platform Release Matrix
| Platform / Target | Full Release Command | Version Bump Only | Git Tag Pattern | CI/CD Workflow | Version Files & Changelog | Distribution Target |
|---|---|---|---|---|---|---|
| Desktop App | pnpm release:desktop | pnpm release:desktop:version | v* (e.g. v0.12.1) | .github/workflows/release-desktop.yml | apps/desktop/package.jsonsrc-tauri/tauri.conf.jsonsrc-tauri/Cargo.tomlapps/desktop/CHANGELOG*.md | Cloudflare R2 (/inkpoint/desktop/)Homebrew TapGitHub Releases |
| Web Playground | pnpm release:web | pnpm release:web:versionpnpm release:web:publish | web-v* (archival tag only) | .github/workflows/release-web.yml | apps/web/package.jsonapps/web/CHANGELOG*.md | Vercel Production (editor.jiaqi.im/playground) |
| Official Site | pnpm release:site | N/A | Triggered on release or manual | Vercel CLI Prebuilt Deploy | Sourced from Desktop & Web changelogs | Vercel Production (editor.jiaqi.im) |
| Distribution Worker | pnpm deploy:worker | N/A | Manual / Infrastructure deploy | Cloudflare Worker CLI | infra/distribution-worker | Cloudflare Edge (download.jiaqi.im) |
| uTools Plugin | Manual Review | apps/utools/package.json | utools-v* | .github/workflows/release-utools.yml | apps/utools/package.jsonapps/utools/CHANGELOG*.md | uTools Developer Center (manual submission) |
| Public NPM Packages | pnpm release:packages | pnpm changeset:version | <pkg>@<version> | .github/workflows/release-npm-packages.yml | packages/*/package.jsonpackages/*/CHANGELOG.md | npm registry (https://registry.npmjs.org) |
3. Platform Release Workflows
3.1 Desktop Release (apps/desktop)
- Pre-check: Ensure working tree is clean and
pnpm verifypasses. - Execute release:
# Interactive mode (prompts for patch / minor / major / beta / notes) pnpm release:desktop # Or non-interactive CLI: pnpm release:desktop patch --notes "修复已知缺陷" - What happens automatically:
- Updates version in
apps/desktop/package.json,tauri.conf.json,Cargo.toml. - Prepends new version block into
apps/desktop/CHANGELOG.mdandapps/desktop/CHANGELOG_EN.md. - Creates commit
chore(release): release vX.Y.Zand annotated tagvX.Y.Z. - Pushes tag to origin, triggering
.github/workflows/release-desktop.yml. - GitHub Actions builds macOS (DMG + updater), Linux (AppImage + DEB), and Windows (Setup EXE).
- Uploads artifacts to Cloudflare R2, updates
version.json, purges CDN cache, and triggerspnpm release:site.
- Updates version in
3.2 Mobile (Android / iOS)
Mobile is no longer released: there is no release script, no tag-triggered CI, and no changelog to update. The site and the distribution gateway only offer the last published builds (Android 0.2.1, iOS 0.2.1). Newer builds are compiled locally:
pnpm build:android # dist-mobile/Inkpoint_<version>.apk (needs JDK 17 + Android SDK)
pnpm build:ios # dist-mobile/Inkpoint-<version>-unsigned.ipa (needs macOS + Xcode)
3.3 Web Playground Release (apps/web)
- Scheme A - Vercel CLI Direct Deploy (Recommended):
Directly pulls production environment, prebuilds, and deploys to Vercel production without polluting GitHub Releases.pnpm release:web - With Version & Changelog Archive:
Updatespnpm release:web:publish patch --notes "新增 MDX 动态预览支持"apps/web/package.json, updatesapps/web/CHANGELOG*.md, pushesweb-v*archival tag, and deploys.
3.4 Official Site Deployment (site)
- Deploy Site:
pnpm release:site - Mechanics:
- Uses Vercel CLI with prebuilt output (
pull->build --prod->deploy --prebuilt). - Reads
apps/desktop/CHANGELOG.mdandapps/web/CHANGELOG.md. /changelogroute uses Next.js ISR (export const revalidate = 300) for high-performance edge caching.
- Uses Vercel CLI with prebuilt output (
3.5 Distribution Worker Deployment (infra/distribution-worker)
- Deploy Worker:
pnpm deploy:worker - Deploys updated Cloudflare Worker handling download redirects, device directories, and release API metadata.
3.6 Public NPM Packages Release (packages/*)
- Prerequisite: Ensure
NPM_TOKENis configured in GitHub Repository Secrets (Settings -> Secrets and variables -> Actions). - Changeset generation: When modifying public packages (
core,editor,plugin-sdk,shared,markdown-fidelity,plugin-host), runpnpm changesetin your PR branch, choose the SemVer type, write an English description, and commit.changeset/*.md. - Automated Versioning: When changesets merge into
main,.github/workflows/release-npm-packages.ymlautomatically updates the "chore(release): version npm packages" PR with bumped versions and changelogs. - Automated Publishing: Merging the "Version Packages" PR triggers
.github/workflows/release-npm-packages.yml, executingpnpm release:packages(which runspnpm verify:packagesand publishes to npm with Git tags). - Reference: See
docs/agent/release/npm_automated_release_changesets.md.
4. Post-Release Verification Checklist
After the release workflow runs, verify each checkpoint:
- GitHub Actions Workflow:
Ensure all matrix jobs (build, package, upload, site deploy) are green.gh run list --limit 3 gh run watch <run_id> - Distribution Edge API:
Confirmcurl -s https://download.jiaqi.im/api/inkpoint/releases | jq '{latestDesktopVersion}'latestDesktopVersionmatches the expected version. - Direct Download Links:
- Desktop:
https://download.jiaqi.im/inkpoint/desktop/macos/latest
- Desktop:
- Website Rendering:
- Home page: check that the download CTA displays the correct version badge.
- Changelog page (
/changelog): verify the tabs (Desktop, Web, Model) show the newly released version and notes.
5. Troubleshooting & Rollback SOP
- Broken Release CI Job:
- Inspect failed logs:
gh run view --log-failed <run_id>. - If caused by network timeout or temporary R2 token glitch, re-run failed jobs via GitHub CLI or Actions UI.
- If code or script error, fix on a
fix/<description>branch, land PR tomain, and re-trigger release.
- Inspect failed logs:
- R2 Edge Cache Stale:
Run cache purge manually:
node scripts/release/purge-download-cache.mjs - Never delete or rewrite published tags on remote:
Always increment with a new patch release (e.g.
0.12.2or0.2.1) to preserve immutable download history.
6. Pitfalls
--yessilently drops the PR link:publish-desktop.mjsprompts for the associated PR only when stdin is a TTY. Running non-interactively with--yesskips that prompt, soplan.prbecomesundefinedand the changelog heading is written as## 0.23.0 - 2026-11-17instead of## 0.23.0 - 2026-11-17 (#261). Always pass--pr <number>together with--yes:
Instance:pnpm release:desktop minor --pr 261 --notes "..." --notes-en "..." --yesv0.23.0shipped without(#261)and the site/changelogpage renders straight fromapps/desktop/CHANGELOG.md, so the gap is user-visible. Because published tags must not be rewritten, the only in-band fix is a new patch release; correcting the markdown onmainfixes the site without shipping a redundant build, but leaves already installed clients showing the old heading.- Verify against the registry, not just the CI status: a green
Release NPM Packagesrun reportsSuccessfully published, yetnpm view <pkg>@<version>can still 404 for a minute or two while the registry propagates. Queryhttps://registry.npmjs.org/<pkg>directly and re-check before declaring a package missing (or published).
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 318k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 117k | Updated | Claude CodeCodex | Verified | Install |