release-new-version

# Release a New Version Use this for Nightly builds, stable desktop releases, and requested mobile store distribution. A stable desktop release must come from `main`, after the changelog and required CLI, MCP, API, agent-package, and documentation updates are accurate, validated, and merged. Desktop and watchOS share the marketing version in `release-version.json`. iOS and Android use `apps/mobile/release-version.json`. Platform build numbers and publication schedules remain independent. ## Core Rule Do not trigger a stable release from an unmerged branch. Complete the release surface review and changelog below, merge the required changes to `main`, then freeze the candidate and release that merged commit through its Nightly tag. ## Nightly and Stable Operations - Existing users and the main download remain on stable. Nightly is an explicit separate-app install, with its own updater feed and CLI command. It opens the same local database as stable; settings, store, and sign-in stay per app. - The team uses Nightly for daily meetings. Volunteers can join through the announcement in the next stable changelog and product-update newsletter. - `.github/workflows/desktop_nightly.yaml` runs daily at 15:00 UTC (midnight KST) and can be dispatched manually from `main`. It runs desktop JS/i18n and native CI, including source CloudSync rebuilds, before building and publishing all desktop platforms through `desktop_cd.yaml` with `channel=nightly`. - Nightly versions are `<shared-version>-nightly.<n>`, where `<n>` counts up from 1 for each base version (`1.4.24-nightly.1`, `1.4.24-nightly.2`, ...) and resets when `release-version.json` moves to the next stable. Each build snapshots `packages/changelog/nightly.md` into the app and a GitHub prerelease tagged `desktop_nightly_v<nightly-version>`. Maintain that file as curated, user-facing changes since the previous stable release; do not generate a raw commit dump. Nightly notes never belong in the website's stable changelog. - Target weekly ordinary stable releases. Select a published Nightly commit, pin the team's app to it for 2–3 working days, and record real meeting results. Disable automatic updates while testing that candidate. CI or elapsed time alone is not evidence of use. Confirm recording/transcription, saved notes after restart, sync, and stable-to-candidate upgrades on shipped platforms. - One release owner records the candidate, Nightly release/run, testing results, unresolved issues, and go/no-go decision in the release task. A serious regression postpones publication. Candidate fixes require renewed affected testing; newer main features wait for the next candidate. - Nightly and stable are separate signed packages. Build stable from the tested commit and verify its install/upgrade behavior before publication; do not present the Nightly binary as byte-identical to the stable artifact. - For an urgent stable hotfix, start from the latest stable tag, carry the minimal fix into main, and verify the patch. Record the owner's explicit exception to the usual Nightly testing period; do not bundle unrelated work. The candidate must still be merged into main before publication. If main has advanced, dispatch `desktop_cd.yaml` with `channel=nightly` on the merged hotfix branch, supplying its exact SHA, then use the resulting Nightly tag for stable verification and publication. This preserves the minimal patch. - Shared APIs and synced data must stay compatible with existing stable clients. Nightly and stable write the same local database, and the apps refuse to run at the same time. A `-- breaking` migration published in Nightly locks stable users out of their notes until stable ships it: keep schema changes additive (see the root `AGENTS.md`), and land a breaking migration only in the candidate that becomes the next stable release, so the lockout ends when that release publishes. ### Publish and verify Nightly ```bash gh workflow run desktop_nightly.yaml --ref main gh run list --workflow desktop_nightly.yaml --limit 5 ``` Verify the exact SHA and all called jobs, not only the aggregate status. A failed run needs a fresh dispatch. Confirm the GitHub prerelease/tag, signed installers, CrabNebula `nightly` downloads, and every platform's Nightly update response. Install the published build and exercise Nightly-to-Nightly updating, auth, sharing links, and the embedded CLI. Confirm stable remains on the stable feed. The first published Nightly needs this verification before announcing it. Do not send the newsletter or announce Nightly as available until the Nightly builds, update feed, and `https://anarlog.so/download/nightly/` are live and verified. Use the [newsletter skill](../product-update-newsletter/SKILL.md) for the announcement. Nightly publication does not publish a website changelog or submit to stores. ## Scope Boundary Establish the exact desktop version and requested mobile destination before dispatching. A desktop release includes its existing Microsoft Store workflow; it does not imply mobile submission. When mobile is requested, distinguish TestFlight and Google Play internal testing from public App Store review and Google Play production rollout. Honor authorization already given in the task; do not ask again for an approved destination. App Store here means the iOS app. The repository deliberately has no Mac App Store release lane; do not recreate one as part of a desktop or mobile release. Every desktop release includes the CLI, local and hosted MCP, API, agent-package, and documentation freshness review below, and deploys any hosted service that has unpublished changes this release needs. The CLI and local MCP ship inside the desktop package; hosted services, plugin catalogs, and docs have separate publication paths. Keep their versions independent and record their source SHAs. An unchanged surface needs evidence that its published version still covers the candidate; it does not need an artificial version bump or redeployment. Honor existing authorization for service and documentation publication. If a required external action is not authorized, finish preparing and validating the concrete change before asking for that action. When a hosted service has unpublished changes this release needs, dispatch its CD workflow during the release; do not leave the deploy as a follow-up. Do not call the complete release finished while a required surface is stale or awaiting publication. Release and QA are separate, explicitly requested workflows. Do not read or run `qa-critical-ux` or `qa-cli-mcp-api` solely because the user asked for a release. A release does not require a report from either optional QA skill. The Nightly candidate testing and final stable package verification above are part of this release operation; report their actual evidence separately. The contract, packaging, and publication checks in this skill are required release verification; they do not invoke either optional QA workflow. If the user explicitly asks for both release and QA, follow the requested order and report the outcomes separately. Do not infer that a QA result approves or blocks the release. ## Release Workflow Requirements The desktop path covers macOS, Windows, and Linux. Requested mobile distribution follows the separate native-build and store steps below. The patched CloudSync vendor bundle is rebuilt from source and cancellation-tested on every desktop lane: `rebuild-macos.sh` for Apple Silicon and Intel, `rebuild-windows.sh` under UCRT64 in `windows_ci`, and `rebuild-linux.sh` in `linux_ci` for x86_64 and aarch64. Each lane then runs `cargo test -p cloudsync` and `cargo test -p db-core cloudsync::` against that freshly built library, covering the stalled-network, logout, configuration cleanup/init, worker-drain, and immediate-local-write cancellation gates. The rebuild steps run on `workflow_dispatch` or the Nightly caller with `rebuild_cloudsync=true`, so a routine pull-request run does not prove them. Dispatch `desktop_ci.yaml` against the candidate SHA and confirm the `cloudsync-windows-*` and `cloudsync-linux-*` artifacts before treating a desktop lane as approved. Do not treat macOS artifacts or Rust-only tests as cross-platform approval. Check the mobile coverage separately; its current Android job does not provide the iOS cancellation-test coverage. ## Preflight 1. Inspect the workflow before assuming release behavior: ```bash cat .github/workflows/desktop_cd.yaml cat .github/workflows/desktop_ci.yaml cat .github/workflows/desktop_publish.yaml cat .github/workflows/desktop_store_publish.yaml cat .github/workflows/cli_ci.yaml cat .github/workflows/api_ci.yaml cat .github/workflows/api_cd.yaml cat .github/workflows/stripe_cd.yaml cat .github/workflows/db_cd.yaml cat .github/workflows/web_ci.yaml cat .github/workflows/web_cd.yaml ``` 2. Validate the explicit stable version requested by the user: ```bash VERSION=<version> [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]] node scripts/release-version.mjs "$VERSION" node scripts/release-version.mjs --check "$VERSION" test -f "packages/changelog/content/$VERSION.md" ``` Stable desktop releases never infer a version. The workflow requires the exact stable semantic version to match `release-version.json` and a changelog file. The version command also regenerates `apps/watch/apple/Version.xcconfig`; commit both desktop version files with the release preparation changes. Expo reads `apps/mobile/release-version.json`. A desktop bump does not change or authorize mobile publication. 3. Identify the latest stable desktop tag and the commits that will ship: ```bash gh release list --limit 20 gh api repos/fastrepl/anarlog/compare/<latest-desktop-tag>...main git log --oneline <latest-desktop-tag>..<candidate-sha> ``` Verify the latest published, non-prerelease `desktop_v<semver>` tag through GitHub. GitHub's compare file list can be truncated; use local history and diffs for the complete changelog review. Use read-only `git` commands for inspection. Use the `but` skill for local version control, and GitHub tools for PR metadata and merges. Do not force-fetch tags or force-push to prepare a release. ## Release Surface Review Complete this before freezing the candidate, including when only preparing a release. Review the full product diff since the last stable desktop tag, not just CLI/API paths. Also compare each independently published surface with its last published source SHA so previously unshipped changes are not missed. For each user-facing change, record the affected surfaces, required updates, validation, and publication status in the release task or PR. Use `unchanged` or `not applicable` only with a concrete reason. Check that supported agent workflows expose the new or changed product behavior. Fix drift before release; an intentional capability difference must be documented. A missing capability that needs a product decision requires an explicit deferral, not a silent skip. | Surface | Review against the candidate | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | CLI and shared agent access | `apps/cli`, `crates/agent-access`, and CLI contract snapshots: commands, flags, JSON fields/errors, pagination, exports, local/cloud selection, and supported data formats. Trace changed product behavior through these implementations; rebuilding alone does not establish coverage. | | Local and hosted MCP | `apps/cli/src/mcp.rs`, `crates/api-cloud/src/mcp.rs`, and `crates/mcp`: tool/resource schemas, output, protocol compatibility, and authentication. Derive expectations from current source and snapshots, never a hardcoded historical tool count. Preserve documented local proposal approval and hosted read-only boundaries. | | API and generated client | `apps/api`, `crates/api-cloud`, and affected auth/sync crates; `apps/api/openapi.gen.json` and `packages/api-client/src/generated`. Check routes, payloads, errors, auth scopes, and compatibility with already shipped desktop/mobile/CLI clients. | | Agent skills and plugins | Authored `skills/anarlog`, generated `agent-plugins/anarlog` and `docs/skill.md`, native manifests, and repository marketplace entries. Update instructions and examples, bump the plugin's own version when its package changes, and keep manifests and their tests aligned. | | Documentation and discovery | Read `docs/AGENTS.md`; review affected product guides, installation/upgrade instructions, CLI/MCP/Cloud references, examples, troubleshooting, screenshots, `docs/docs.json`, and `apps/web/public/llms.txt`. Include the public skill, Mintlify's `llms.txt`/`llms-full.txt`, and the website changelog in publication verification. Document shipped behavior and actual platform availability. | | Hosted services | Compare each independently deployed service with its last published SHA/tag: API/hosted MCP (`api_cd.yaml`, `api_v*`), Stripe (`stripe_cd.yaml`, `stripe_v*`), hosted Postgres (`db_cd.yaml`), website (`web_cd.yaml`, `web_v*`), and Mintlify docs. Record whether the candidate needs a redeploy. | Review related release dependencies when affected: SQLite/CloudSync and hosted schema migrations, downgrade compatibility, native bindings, mobile/watch consumers, billing/auth configuration, installer/updater and package channels, and release version attribution in error reporting. Record backend-first rollout and rollback requirements before publishing a client that depends on them. Follow each component's instructions; this review does not authorize mobile submission or unrelated infrastructure changes. ### Validate and synchronize Run the full locally reproducible jobs from `cli_ci.yaml` and `api_ci.yaml` for affected code, plus consumer checks from root `AGENTS.md`. CLI CI includes command/MCP contract snapshots, documentation coverage, Linux/Windows smoke tests, plugin checks, and Mintlify validation. API CI checks hosted MCP/auth and OpenAPI generation. A passing snapshot or docs check does not prove that a new product feature was considered; retain the surface review above. When the API contract changes, regenerate the spec and client, review the diff, and typecheck the client and affected consumers: ```bash cargo test -p api gen_openapi_json pnpm -F @anlg/api-client openapi pnpm -F @anlg/api-client typecheck ``` Edit the authored agent skill and references, then generate their mirrors with `node scripts/publish-anarlog-skill.mjs`. The script writes repository files; it does not publish a website or install a plugin. Before every release, run: ```bash node scripts/publish-anarlog-skill.mjs --check node --test scripts/publish-anarlog-skill.test.mjs ``` Use the Mintlify version pinned in `cli_ci.yaml` to run `validate` and `broken-links --check-anchors --check-redirects` from `docs/`. Run affected web checks when changing website content or discovery files. Regenerate again to confirm generated output is stable, and include all intended generated changes before freezing the candidate. ## Changelog Gate The changelog is required alongside the release surface review. Before releasing either channel: 1. Open `packages/changelog/content/AGENTS.md` and follow its instructions. 2. For stable, confirm `packages/changelog/content/<version>.md` exists. For Nightly, use `packages/changelog/nightly.md`. 3. Compare the file against the desktop user-facing changes since the latest `desktop_v*` tag. 4. If the changelog is missing or incomplete, update it before release. Changelog entries should be worth reading for app users. Exclude internal-only refactors, CI changes, infra noise, and implementation details unless they explain a user-visible change. If a user-facing change came from a pull request by someone outside the Fastrepl org, that item must credit them. See `packages/changelog/content/AGENTS.md`. Each changelog file must include: ```md --- date: "YYYY-MM-DD" summary: "One concise, user-facing sentence for the changelog index preview." --- ``` After editing the changelog, run: ```bash pnpm exec dprint fmt --allow-no-files packages/changelog/content/<version>.md pnpm exec dprint check --allow-no-files packages/changelog/content/<version>.md pnpm -F @anlg/changelog typecheck ``` ## Merge to Main Only after the changelog and required release surface updates are accurate and validation passes: 1. Commit the changelog and surface updates in coherent commits. 2. Open or update their PRs. 3. Wait for CI and required review state to be clear. 4. Merge the release preparation PRs to `main`. 5. Verify `main` contains the changelog and all required surface updates. 6. Record the resulting `main` SHA, publish a Nightly from it, and retain its immutable `desktop_nightly_v<nightly-version>` tag as `CANDIDATE_REF`. 7. Complete the Nightly candidate testing period before building stable. Keep development on main; do not replace the candidate with its latest head. If using GitButler, prefer: ```bash but diff but commit -b chore/release-changelog -m "Update desktop release changelog Refresh the desktop changelog for the next stable release." <file-or-hunk-ids> but pr new chore/release-changelog -t ``` Use actual IDs from `but diff` / `but status -fv`; do not invent IDs. ## Deploy Hosted Services This is a required release action, not optional follow-up. After the candidate is on `main`, decide for each independently published service and then deploy the ones that need it before publishing the desktop client. For each service: 1. Find the last successful CD run and, when one exists, the published tag (`api_v*`, `stripe_v*`, `web_v*`). Hosted Postgres has no version tag; use the last successful `db_cd.yaml` run SHA. 2. Diff that SHA against the candidate for that service's source. Re-read the workflow if the checkout, image context, or migration path is unclear. 3. Dispatch the CD workflow on `main` when the candidate contains unpublished changes this release needs, or that users would otherwise miss. Reuse a live deployment only when its SHA already includes those changes. 4. An unchanged service needs that live SHA/version recorded. Do not dispatch a no-op redeploy to make the checklist look complete. 5. Confirm the target is Anarlog before any service access; never access `*-char`. Check the run's `headSha` against the intended SHA and wait for the job and tag (when the workflow creates one). ```bash gh workflow run api_cd.yaml --ref main gh workflow run stripe_cd.yaml --ref main gh workflow run db_cd.yaml --ref main gh workflow run web_cd.yaml --ref main gh run list --workflow api_cd.yaml --limit 3 gh run view <run-id> --json headSha,url ``` | Service | Workflow | Deploy when | Live check |