Release checklist

Use this checklist before publishing anything user-facing. Pick the validation path that matches the change, then confirm the diff is scoped and public-safe before handing it to a release workflow.

Choose the validation path

Change type	Minimum validation
Documentation-only change	Inspect the diff, build the affected docs site, and check links or search when applicable
Backend, API, streaming, or session behavior	Run backend tests, restart or reload a local instance, and verify health
Frontend user interface	Build the frontend and run the relevant browser or end-to-end checks
Hosted web entry	Run the site package tests and check the deployed routes
Package or updater release	Verify version sync, installability, app startup, updater metadata, and download metadata

Do not use a lighter path just because a change looks small. Use the path that matches the surface a user can observe.

Documentation fast path

For documentation-only changes, start with the exact diff:

git diff --stat
git diff -- services/docs-site/src/content/docs/

For the Starlight documentation site:

cd services/docs-site
npm run build
npm run check:search

If the change only touches non-rendered Markdown outside the docs site, a diff review may be enough. Public pages should still be checked for broken links, invalid frontmatter, and private information.

Full validation path

Backend changes:

cd backend
python -m pytest tests/ -x -q -n 2

Frontend changes:

cd frontend
npm run build
npm run test:e2e

After restarting or reloading a local instance, verify health:

curl -s http://127.0.0.1:${JARVIS_PORT:-8888}/api/v1/health | python3 -m json.tool

The response should be JSON, report a healthy status, and show the version you intended to run.

Version checks

The repository root VERSION file is the human-edited source for release versions. Before a package or full release, synchronize generated manifests and check that nothing drifted:

python3 scripts/sync-version.py
python3 scripts/sync-version.py --check

All-platform releases may advance the version and updater metadata. A single-platform rebuild should normally reuse the current version and avoid changing updater metadata unless the release runbook calls for a full release.

Package and updater checks

Before publishing packages, verify the actual artifact path that users will receive:

clean install works on the target platform
app starts without a development server
backend health check succeeds after startup
packaged frontend assets are current
updater metadata points to the intended version and signature
public download metadata points to the intended package

Package releases should have explicit maintainer approval. Do not create public tags, releases, or updater metadata as a side effect of an unrelated change.

Diff and redaction checks

Before committing or publishing, inspect the scoped diff:

git diff --stat
git diff --cached

Remove or replace:

API keys, tokens, cookies, and private credentials
private hostnames, server IP addresses, and SSH aliases
user-specific local filesystem paths
private chat transcripts, prompts, or provider responses
internal planning links that are not useful to public users

Use public placeholders such as <your-domain>, <your-port>, and <your-api-key> when an example needs a value.

Final release gate

Before a release goes live:

The validation path for the changed surface has passed.
Version metadata is synchronized when a versioned artifact is involved.
Public release notes describe user-visible changes and omit private details.
Download and updater metadata point at the intended artifacts.
Rollback steps are known for the deployment track being used.