# Releasing causal-triangulations

This guide documents the release flow for `vX.Y.Z`: prepare a dedicated release PR, merge it, create the final annotated tag from the generated changelog,
publish to crates.io, and create the GitHub release.

The release changelog is generated with `git-cliff --tag` through `just changelog-unreleased`, so no temporary local tag is needed.

---

## Conventions and environment

Set these variables to avoid repeating the version string:

```bash
# tag has the leading v, version does not
TAG=vX.Y.Z
VERSION=${TAG#v}
```

Verify your git remotes:

```bash
git remote -v
```

Ensure your local `main` is up to date before beginning:

```bash
git checkout main
git pull --ff-only
```

---

## Step 1: Create a clean release PR

This PR should primarily include version bumps, changelog updates, and documentation updates. All major code changes should already be on `main`.

Small, critical fixes discovered during the release process may be included, but keep them minimal and release-critical.

1. Create the release branch

```bash
git checkout -b "release/$TAG"
```

2. Bump versions

Preferred, if `cargo-edit` is installed:

```bash
cargo set-version "$VERSION"
```

Alternative: edit `Cargo.toml` manually and update `version = "..."` under `[package]`.

Review version references in documentation:

```bash
rg -n "\bv?[0-9]+\.[0-9]+\.[0-9]+\b" README.md docs/ || true
```

3. Generate the release changelog

```bash
# Generates CHANGELOG.md as though TAG already exists, then applies
# markdown hygiene and archives completed minor release series.
just changelog-unreleased "$TAG"
```

`just changelog-unreleased` runs `GIT_CLIFF_OFFLINE=true git-cliff --tag "$TAG" -o CHANGELOG.md`, then `postprocess-changelog`, then `archive-changelog`. The
root changelog keeps Unreleased plus the active minor series; older completed minor series live under `docs/archive/changelog/`.

4. Validate the release branch

```bash
just ci
cargo publish --dry-run
```

5. Stage and commit release artifacts

```bash
git add Cargo.toml Cargo.lock CHANGELOG.md docs/

git commit -m "chore(release): release $TAG

- Bump version to $TAG
- Update changelog with latest changes
- Update documentation for release"
```

6. Push the branch and open a PR

```bash
git push -u origin "release/$TAG"
```

PR metadata:

- Title: `chore(release): release $TAG`
- Description: Clean release PR with version bump, changelog, and documentation updates. No feature work.

### Handling fixes discovered during the release process

If you discover issues after generating the changelog:

1. For critical fixes that must be in this release, make and commit the fix, then regenerate the release changelog:

   ```bash
   just changelog-unreleased "$TAG"
   git add CHANGELOG.md docs/archive/changelog/
   git commit -m "docs: update changelog with release fixes"
   ```

2. For non-critical fixes, document them as known issues in the release notes or include them in the next release.

---

## Step 2: After the PR is merged into main

1. Sync your local `main` to the merge commit

```bash
git checkout main
git pull --ff-only
```

2. Create the final annotated tag using the changelog content

```bash
# Creates the annotated tag from the matching CHANGELOG.md section.
# Archived versions are read from docs/archive/changelog/ automatically.
# For large changelogs (>125KB), the tag message points to the changelog
# section instead of embedding the full content.
just tag "$TAG"
```

3. Optional: verify the tag message content

```bash
git tag -l --format='%(contents)' "$TAG"
```

4. Push the tag

```bash
git push origin "$TAG"
```

5. Publish to crates.io

```bash
cargo publish
```

6. Create the GitHub release with notes from the tag annotation

```bash
gh release create "$TAG" --title "$TAG" --notes-from-tag
```

Always set the GitHub release title to the exact tag string, including the leading `v`.

---

## Notes and tips

- Do not create a temporary local release tag for changelog generation; use `just changelog-unreleased "$TAG"`.
- Keep the release PR scoped to version, changelog, archive, and documentation changes.
- `just changelog` regenerates the current changelog from existing tags and may update `docs/archive/changelog/`.
- `just changelog-unreleased "$TAG"` is for release PR preparation before the final tag exists.
- `just tag "$TAG"` is for the final post-merge annotated tag.
- If multiple files reference the version, confirm all of them are updated consistently.
