release

# release

Bump version, commit, tag, and create a draft GitHub Release. Use when the user
asks to "release", "bump version", "tag a release", or "publish".

## Instructions

1. **Determine the new version.** Read the current version from
   `python/pyproject.toml` and increment the patch number automatically.
   If the user specifies a version explicitly, use that instead.

2. **Run the bump script:**
   ```sh
   python3 tools/bump-version <new_version> --check
   ```
   This updates all Cargo.toml files, pyproject.toml, CHANGELOG, README,
   docs, and lib.rs references. `--check` verifies `cargo check` passes.

   The bump script adds a `## <new_version>` section to `CHANGELOG.md`
   with a `*No changes yet.*` placeholder. Do NOT edit the CHANGELOG
   before running bump-version — it will create a duplicate section.

3. **Write the CHANGELOG.** After bump-version runs, replace the
   `*No changes yet.*` placeholder in `CHANGELOG.md` with real entries.
   Use `git log` to find commits since the previous release tag.

   Focus on **user-visible changes only**:
   - New features, new CLI flags, new API surface
   - Bug fixes that affected users
   - Breaking changes or renamed options
   - Documentation improvements (briefly)

   Do NOT include:
   - Internal refactors, code cleanup, clippy fixes
   - CI/release pipeline plumbing
   - Changes to dev tooling or build scripts

   Keep entries concise — one line per change, no sub-bullets.

4. **Commit and push:**
   ```sh
   git add -A
   git commit -m "$(cat <<'EOF'
   synq: bump version to <new_version>
   EOF
   )"
   git push origin HEAD:main
   ```

5. **Create and push the tag:**
   ```sh
   git tag v<new_version>
   git push origin v<new_version>
   ```

6. **Create a draft GitHub Release.** Read CHANGELOG.md to get the release
   notes for this version. Ask the user if they want to edit the notes or
   if the CHANGELOG content is sufficient.
   ```sh
   gh release create v<new_version> --draft --title "v<new_version>" \
     --notes "$(release notes here)"
   ```
   The tag must already exist on the remote before `gh release create`
   will work — that's why we push it first.

   Pushing the tag triggers build workflows that upload artifacts to the
   draft release:
   - `release.yml` — cargo-dist builds CLI binaries, Homebrew tap, installers
   - `publish-crates.yml` — publishes to crates.io
   - `vscode-extension.yml` — builds VS Code .vsix artifacts
   - `release-amalgamation.yml` — C source amalgamation archive
   - `release-clib.yml` — prebuilt C shared library archive

7. **Report** the draft release URL to the user and remind them to publish
   the release manually once the builds complete and look good.