release-policy git:20261024.a391928A

Immutable. This exact content never changes and is served at /api/v1/blob/c758c670b50ab970.

---
description: Release, versioning, and signing policy for setmac
alwaysApply: true
---

# Release Policy

- Use Conventional Commits and keep one logical change per commit.
- Let semantic-release own version bumps. It writes `[tool.setmac].version` in `pyproject.toml` and `__version__` in `cli/src/setmac/__init__.py`; never hand-edit them. The `[project].version` fields stay `0.0.0` because prerelease versions like `1.2.0-canary.1` are not valid PEP 440.
- Default to prereleases: push `canary` for `-canary.N`, push `beta` for `-beta.N`.
- Every release job runs in the protected `release` environment and waits for the maintainer's approval; release commits and tags are GPG-signed there (`scripts/ci-signing-key.sh`).
- Only publish stable when the user explicitly asks. Stable releases run through the manual `Release Stable` workflow from `main`.
- Keep release artifacts as `dist/Setmac.dmg` and `cli/dist/setmac-cli`.
- Release builds must run through `scripts/release-build.sh`, which signs artifacts and only notarizes when Apple secrets are configured.
- If Apple signing secrets are missing, treat builds as ad-hoc signed and include the Gatekeeper workaround in release/install notes:
  - `xattr -cr /Applications/Setmac.app`
  - or Control-click `Setmac.app` and choose `Open`