> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sharecursor.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Releasing

> The exact, repeatable process to ship a new ShareCursor version — SemVer policy, the release checklist, and what CI builds.

This is the exact, repeatable process to ship a new version. Following it means
end users always get working one-click installers and the history stays clean.

## Versioning policy (SemVer)

`MAJOR.MINOR.PATCH`:

| Bump      | When             | Wire/config                                                                                        |
| --------- | ---------------- | -------------------------------------------------------------------------------------------------- |
| **PATCH** | bug fixes        | no wire or config changes                                                                          |
| **MINOR** | new features     | backward-compatible (old configs still load via `#[serde(default)]`; `PROTOCOL_VERSION` unchanged) |
| **MAJOR** | breaking changes | also bump `PROTOCOL_VERSION` in `crates/protocol/src/lib.rs` and document the migration            |

The crate version lives in `Cargo.toml` under `[workspace.package]`; all crates
inherit it. The Windows installer default, website schema, lockfile, and
changelog mirror that version. Run `node scripts/check-release-version.mjs
X.Y.Z` before tagging to verify every release surface.

## Release checklist

<Steps>
  <Step title="Green build & tests">
    ```bash theme={null}
    cargo test                       # native
    cargo test --no-default-features # core
    cargo build --release --features tray,gui
    cargo run --release -- bench --encrypted   # no latency regression
    ```
  </Step>

  <Step title="Bump the version">
    Update `Cargo.toml`, the Windows installer default, and the website
    `SoftwareApplication` schema. Run `cargo build` once so `Cargo.lock`
    updates, then run `node scripts/check-release-version.mjs X.Y.Z`.
  </Step>

  <Step title="Update CHANGELOG.md">
    Move `## [Unreleased]` items under a new `## [X.Y.Z] - YYYY-MM-DD` heading;
    start a fresh empty `Unreleased`.
  </Step>

  <Step title="Commit on main">
    ```bash theme={null}
    git add -A && git commit -m "release: vX.Y.Z"
    ```
  </Step>

  <Step title="Tag & push">
    This triggers the CI release workflow:

    ```bash theme={null}
    git tag vX.Y.Z
    git push origin main --tags
    ```
  </Step>

  <Step title="Wait for CI">
    `.github/workflows/release.yml` attaches the macOS DMG, Windows installer,
    SHA-256 checksum file, generated Scoop manifest, and generated Homebrew cask
    to the GitHub Release.
  </Step>

  <Step title="Smoke-test and update package repositories">
    Install, launch and connect once on both OSes, then verify the checksums.
    Copy `sharecursor.json` to the Scoop bucket and `sharecursor.rb` to
    `Casks/sharecursor.rb` in the Homebrew tap. These external repositories are
    not changed automatically.
  </Step>

  <Step title="Announce">
    The Release page is the download link for users.
  </Step>
</Steps>

## What CI does

<AccordionGroup>
  <Accordion title="Trigger" icon="play">
    Pushing a tag matching `v*` (or a manual `workflow_dispatch`).
  </Accordion>

  <Accordion title="macos job (macos-14)" icon="apple">
    Adds both Apple targets, runs `packaging/macos/build-app.sh $VERSION` →
    universal `.app` + `.dmg` (arm64 + Intel).
  </Accordion>

  <Accordion title="windows job (windows-latest)" icon="windows">
    `cargo build --release --features tray,gui`, then `choco install innosetup` and
    `ISCC /DMyAppVersion=$VERSION sharecursor.iss` → `.exe` installer.
  </Accordion>

  <Accordion title="release job" icon="rocket">
    Generates checksums plus Scoop/Homebrew manifests from the built artifacts,
    then publishes every file in the GitHub Release.
  </Accordion>
</AccordionGroup>

## Building installers locally

<CodeGroup>
  ```bash macOS theme={null}
  # produces dist/ShareCursor.app + dist/ShareCursor-<ver>.dmg
  bash packaging/macos/build-app.sh 0.6.0
  ```

  ```powershell Windows theme={null}
  # after cargo build --release --features tray,gui
  iscc /DMyAppVersion=0.6.0 packaging\windows\sharecursor.iss
  ```
</CodeGroup>

## Code signing & notarization (current status)

Builds are **unsigned** today (no paid developer certificates):

* **macOS:** Gatekeeper blocks first launch. Removing this friction needs an
  Apple Developer ID (\$99/yr) and a notarization step (`codesign` + `xcrun
  notarytool submit`). The build script already ad-hoc signs so it runs locally.
* **Windows:** SmartScreen shows an "unknown publisher" warning. An EV/OV
  code-signing certificate would remove it.

When certificates are available, add the signing secrets and explicit signing
and notarization steps to the CI jobs.

## Rollback

<Warning>
  If a release is broken, delete the GitHub Release + tag, fix, and re-tag with a
  new PATCH version. **Never re-use a published version number.**
</Warning>