Skip to content

wmasfoe/md-editor / .agents/skills/release

release

Verified

Cross-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

  1. Strict Platform Symmetry: Every client platform (desktop, web, site, utools, worker) has a clear, isolated release lifecycle and namespace.
  2. 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) and CHANGELOG.md (plus CHANGELOG_EN.md) must be updated and committed together.
  3. Changelog-Driven Presentation:
    • The official website (site) and distribution portal read directly from each platform's CHANGELOG.md at 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).
  4. Pre-Release Quality Gate:
    • Working tree must be clean.
    • Must be on the latest main branch.
    • pnpm verify (lint + test + typecheck) must pass 100% before any release command is executed.

2. Multi-Platform Release Matrix

Platform / TargetFull Release CommandVersion Bump OnlyGit Tag PatternCI/CD WorkflowVersion Files & ChangelogDistribution Target
Desktop Apppnpm release:desktoppnpm release:desktop:versionv* (e.g. v0.12.1).github/workflows/release-desktop.ymlapps/desktop/package.jsonsrc-tauri/tauri.conf.jsonsrc-tauri/Cargo.tomlapps/desktop/CHANGELOG*.mdCloudflare R2 (/inkpoint/desktop/)Homebrew TapGitHub Releases
Web Playgroundpnpm release:webpnpm release:web:versionpnpm release:web:publishweb-v* (archival tag only).github/workflows/release-web.ymlapps/web/package.jsonapps/web/CHANGELOG*.mdVercel Production (editor.jiaqi.im/playground)
Official Sitepnpm release:siteN/ATriggered on release or manualVercel CLI Prebuilt DeploySourced from Desktop & Web changelogsVercel Production (editor.jiaqi.im)
Distribution Workerpnpm deploy:workerN/AManual / Infrastructure deployCloudflare Worker CLIinfra/distribution-workerCloudflare Edge (download.jiaqi.im)
uTools PluginManual Reviewapps/utools/package.jsonutools-v*.github/workflows/release-utools.ymlapps/utools/package.jsonapps/utools/CHANGELOG*.mduTools Developer Center (manual submission)
Public NPM Packagespnpm release:packagespnpm changeset:version<pkg>@<version>.github/workflows/release-npm-packages.ymlpackages/*/package.jsonpackages/*/CHANGELOG.mdnpm registry (https://registry.npmjs.org)

3. Platform Release Workflows

3.1 Desktop Release (apps/desktop)

  1. Pre-check: Ensure working tree is clean and pnpm verify passes.
  2. Execute release:
    # Interactive mode (prompts for patch / minor / major / beta / notes)
    pnpm release:desktop
    
    # Or non-interactive CLI:
    pnpm release:desktop patch --notes "修复已知缺陷"
    
  3. What happens automatically:
    • Updates version in apps/desktop/package.json, tauri.conf.json, Cargo.toml.
    • Prepends new version block into apps/desktop/CHANGELOG.md and apps/desktop/CHANGELOG_EN.md.
    • Creates commit chore(release): release vX.Y.Z and annotated tag vX.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 triggers pnpm release:site.

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)

  1. Scheme A - Vercel CLI Direct Deploy (Recommended):
    pnpm release:web
    
    Directly pulls production environment, prebuilds, and deploys to Vercel production without polluting GitHub Releases.
  2. With Version & Changelog Archive:
    pnpm release:web:publish patch --notes "新增 MDX 动态预览支持"
    
    Updates apps/web/package.json, updates apps/web/CHANGELOG*.md, pushes web-v* archival tag, and deploys.

3.4 Official Site Deployment (site)

  1. Deploy Site:
    pnpm release:site
    
  2. Mechanics:
    • Uses Vercel CLI with prebuilt output (pull -> build --prod -> deploy --prebuilt).
    • Reads apps/desktop/CHANGELOG.md and apps/web/CHANGELOG.md.
    • /changelog route uses Next.js ISR (export const revalidate = 300) for high-performance edge caching.

3.5 Distribution Worker Deployment (infra/distribution-worker)

  1. Deploy Worker:
    pnpm deploy:worker
    
  2. Deploys updated Cloudflare Worker handling download redirects, device directories, and release API metadata.

3.6 Public NPM Packages Release (packages/*)

  1. Prerequisite: Ensure NPM_TOKEN is configured in GitHub Repository Secrets (Settings -> Secrets and variables -> Actions).
  2. Changeset generation: When modifying public packages (core, editor, plugin-sdk, shared, markdown-fidelity, plugin-host), run pnpm changeset in your PR branch, choose the SemVer type, write an English description, and commit .changeset/*.md.
  3. Automated Versioning: When changesets merge into main, .github/workflows/release-npm-packages.yml automatically updates the "chore(release): version npm packages" PR with bumped versions and changelogs.
  4. Automated Publishing: Merging the "Version Packages" PR triggers .github/workflows/release-npm-packages.yml, executing pnpm release:packages (which runs pnpm verify:packages and publishes to npm with Git tags).
  5. Reference: See docs/agent/release/npm_automated_release_changesets.md.

4. Post-Release Verification Checklist

After the release workflow runs, verify each checkpoint:

  1. GitHub Actions Workflow:
    gh run list --limit 3
    gh run watch <run_id>
    
    Ensure all matrix jobs (build, package, upload, site deploy) are green.
  2. Distribution Edge API:
    curl -s https://download.jiaqi.im/api/inkpoint/releases | jq '{latestDesktopVersion}'
    
    Confirm latestDesktopVersion matches the expected version.
  3. Direct Download Links:
    • Desktop: https://download.jiaqi.im/inkpoint/desktop/macos/latest
  4. 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:
    1. Inspect failed logs: gh run view --log-failed <run_id>.
    2. If caused by network timeout or temporary R2 token glitch, re-run failed jobs via GitHub CLI or Actions UI.
    3. If code or script error, fix on a fix/<description> branch, land PR to main, and re-trigger release.
  • 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.2 or 0.2.1) to preserve immutable download history.

6. Pitfalls

  • --yes silently drops the PR link: publish-desktop.mjs prompts for the associated PR only when stdin is a TTY. Running non-interactively with --yes skips that prompt, so plan.pr becomes undefined and the changelog heading is written as ## 0.23.0 - 2026-11-17 instead of ## 0.23.0 - 2026-11-17 (#261). Always pass --pr <number> together with --yes:
    pnpm release:desktop minor --pr 261 --notes "..." --notes-en "..." --yes
    
    Instance: v0.23.0 shipped without (#261) and the site /changelog page renders straight from apps/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 on main fixes 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 Packages run reports Successfully published, yet npm view <pkg>@<version> can still 404 for a minute or two while the registry propagates. Query https://registry.npmjs.org/<pkg> directly and re-check before declaring a package missing (or published).
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 318kUpdated Claude CodeCodexVerifiedInstall
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: 196kUpdated Claude CodeCodexVerifiedInstall
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: 118kUpdated Claude CodeCodexVerifiedInstall
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: 117kUpdated Claude CodeCodexVerifiedInstall