# Releasing

Version tags publish npm-format tarballs through GitHub Releases. This project does not publish to the npm registry.

## One-time repository setup

1. Create the GitHub repository with `main` as its default branch.
2. When publishing under a different owner, replace the owner (`ruisenbai`) in `package.json`, Markdown files, and `.github/ISSUE_TEMPLATE/config.yml`.
3. Enable GitHub Discussions and private vulnerability reporting so the links in `SUPPORT.md` and `SECURITY.md` work.
4. Protect `main`, require the `CI` workflow, and require pull-request review before merging.
5. Keep GitHub Actions permission to write repository contents so the Release workflow can create tags and attach tarballs.

Do not replace the contributor copyright in `LICENSE` unless the project has a specific copyright holder. Contributions are accepted under the same MIT License through `CONTRIBUTING.md`; no separate CLA is required.

## Release checklist

For `1.1.7`, the Host target is master commit `8bd073392e` (package version `0.2.2-alpha.3`); [Compatibility](docs/compatibility.md#dependency-source) records its official source commit. Record executed checks and outstanding manual checks separately; updating the version, dependency lockfile, or documentation does not establish release readiness. Check the dedicated **Settings → Annotations** page, its annotation record, sent-note reattachment, Inbox-only queue updates, unsynchronized Inbox snapshots, next-step exclusion, clickable user/steering references, and Markdown file-link selection and restoration before release. Capture repository screenshots from the current Chinese Web profile, including the main Settings page.

1. Move relevant entries from `Unreleased` into a dated version section in `CHANGELOG.md`.
2. Update `version` in `package.json`; refresh `pnpm-lock.yaml` only when the complete dependency family is available from its registry.
3. For a baseline whose registry packages contain all required APIs, run:

   ```bash
   pnpm install --frozen-lockfile --strict-peer-dependencies
   pnpm verify
   pnpm test:browser
   pnpm test:profile
   pnpm test:coverage
   pnpm pack --pack-destination artifacts
   ```

   The `0.2.2-alpha.3` registry family includes the required interfaces. To verify source artifacts as CI does, follow [Official source verification](docs/development.md#official-source-verification) and [Packaging](docs/development.md#packaging). Report the dependency source and commands actually used; source overrides and temporary lockfiles remain verification inputs only.

4. Inspect the tarball file list, package version, and exact `engines.dsh` and peer declarations, then test-install it into a disposable DSH Web profile using the declared host version.
5. Commit and push the release source. When the registry path is available, push an annotated `v<version>` tag and let the Release workflow build both the versioned tarball and the stable `dsh-annotation.tgz` alias used by plugin catalogs. For an unpublished baseline, create a draft GitHub Release with the locally verified versioned tarball, an identical `dsh-annotation.tgz` copy, and the pushed commit as its target; the workflow recognizes those prebuilt assets instead of attempting a registry install.
6. Confirm the workflow accepts the tag and both assets, then publish the draft and verify the public downloads. Compare the downloaded assets byte for byte; the workflow only detects their filenames. The public Release body must state the exact `engines.dsh` host requirement and link `docs/compatibility.md`; generated notes alone are insufficient. Distinguish executed checks from manual checks that remain unverified.
7. For a catalog update, confirm `engines.dsh` matches every lockstep DSH peer, keep `screenshots.json` at 1-8 repository-owned images, and update `data/plugins/ruisenbai__dsh-annotation.yml` in `awesome-dsh-plugin`. Set and keep its category at `session` and preserve its stable tarball alias. Submit the single YAML entry change; current catalog rules regenerate both READMEs on main after merge. Recheck the catalog contribution guide before later releases.

The tag must exactly match `v` plus the package version. The workflow rejects a version mismatch. It uses the prebuilt path only when both the versioned filename and stable alias exist; otherwise it attempts the registry build.