# Releasing and deployment

[Documentation index](README.md) · [Development](development.md) · [Changelog](../CHANGELOG.md)

This page is a maintainer checklist. Preparing metadata is not the same as deciding to release: version changes, GitHub creation, tagging, and npm publication require an explicit release decision.

## Versioning and changelog

The project follows Semantic Versioning:

- patch: compatible fixes;
- minor: compatible features;
- major: incompatible schema, result-contract, command/tool, or behavior changes.

Keep upcoming work under `[Unreleased]` in `CHANGELOG.md`. At release time, choose the version, move the relevant entries under a dated version heading, update `package.json` and `package-lock.json` together, and compare the result contract against [result-contract.md](result-contract.md). Do not rewrite historical release notes merely to match current wording.

## Pre-release checklist

1. Confirm the intended commit, clean worktree, target version, npm package name, repository URL, and license.
2. Review every maintained Markdown file for current names, commands, links, and behavior.
3. Run:

   ```bash
   npm install --package-lock-only
   npm run check
   git diff --check
   npm pack --dry-run --json
   ```

4. Inspect the dry-run file list. It should contain the runtime extension, README/license/package metadata, changelog, contribution/security policies, and useful public docs—never tests, coverage, local settings, credentials, agent state, or machine-specific deployment files.
5. Run the manual TUI matrix in [development.md](development.md#manual-tui-smoke-test-matrix), including installation from a packed artifact when practical.
6. Review `git diff`, ensure no files are staged unexpectedly, then commit the release change through the normal review process.

`npm pack --dry-run` should not create a tarball. If a real `npm pack` is used for installation testing, delete the generated archive afterward.

## GitHub release and npm publication

After approval:

1. push the reviewed release commit to the canonical repository;
2. create an annotated `vX.Y.Z` Git tag on that exact commit and push it;
3. authenticate to the correct npm account and verify publish access to `pi-rich-questions`;
4. run `npm publish` from a clean checkout, using provenance or organization-required controls when configured;
5. compare `npm view pi-rich-questions version dist-tags repository license` with the intended release;
6. install `npm:pi-rich-questions` into a clean Pi environment and run the demo plus one `/rich-questions` extraction;
7. create GitHub release notes from the matching changelog entry.

Never publish from an unreviewed dirty worktree. Never include an npm token in shell history, repository files, logs, or documentation.

## Auto-discovered and development copies

Public installation should use Pi's package manager. Maintainers may also have an auto-discovered extension copy for local testing; it is not the publication source of truth. Before smoke testing, either disable/remove that copy or synchronize it from the reviewed checkout and verify only one registration is active. Reload Pi after changing it. Do not commit local agent-directory paths or copied settings to this repository.

## Rollback

npm versions are immutable. If a published release is broken:

1. preserve evidence and identify the last known-good version;
2. where npm policy allows, deprecate the bad version with a concise reason rather than trying to replace it;
3. tell affected users to install the known-good pinned version, for example `pi install npm:pi-rich-questions@X.Y.Z`;
4. fix forward in a new version, update the changelog, and repeat the full release checklist;
5. update or remove a GitHub release/tag only when repository policy explicitly calls for it—never silently move an existing release tag.

For an unshipped Git commit, revert through normal version control and review. For a local auto-discovered copy, restore from the known-good tag and `/reload`.