# GitHub Workflows Guide

This document explains how release automation works in `.github/` for this repository.

## Covered Files

- `.github/workflows/release-plz.yml`
- `.github/workflows/release.yml`
- `.github/dependabot.yml`
- `release-plz.toml`
- `dist-workspace.toml`
- `cliff.toml`

## Release Flow (Current Behavior)

The release flow is two-stage:

1. Merge a normal dev PR into `main`.
2. `release-plz.yml` runs and updates/creates a release PR (`release-pr` command).
3. Nothing is published yet.
4. Merge the release-plz PR.
5. `release-plz.yml` runs again and performs `release` (creates/pushes version tag).
6. The tag push triggers `release.yml`.
7. `release.yml` builds artifacts, creates GitHub Release assets, and updates Homebrew tap formulae.

This setup prevents the full release pipeline from running on every dev PR merge.

## Workflow: `release-plz.yml`

### Trigger

Runs on:

- `push` to `main`
- Path filtered to:
  - `Cargo.toml`
  - `src/**`

Note:

- If a merge changes only docs or unrelated files, `release-plz.yml` does not run.

### Permissions

Workflow uses:

- `contents: write`
- `pull-requests: write`

### Jobs

`release-plz-pr`

- Uses `release-plz/action@v0.5` with `command: release-pr`.
- Creates/updates the release PR containing version/changelog updates.

`release-plz-release`

- Runs after `release-plz-pr`.
- Uses `release-plz/action@v0.5` with `command: release`.
- On normal dev merges this should no-op.
- After merging the release PR, this job creates the release tag that kicks off `release.yml`.

### Secrets Used

- `RELEASE_PLZ_TOKEN`
- `CARGO_REGISTRY_TOKEN`

### Related Config

`release-plz.toml` controls release-plz behavior:

- changelog source (`cliff.toml`)
- changelog/dependency updates
- git tag creation
- release PR labels

`cliff.toml` controls changelog formatting/grouping.

## Workflow: `release.yml` (cargo-dist)

`release.yml` is generated by cargo-dist and is the artifact/release pipeline.

### Trigger

Runs only on version-like tags:

- `push.tags: '**[0-9]+.[0-9]+.[0-9]+*'`

Important:

- It does not run on pull requests in this setup.

### What It Does

Main jobs:

1. `plan`
2. `build-local-artifacts`
3. `build-global-artifacts`
4. `host`
5. `publish-homebrew-formula`
6. `announce` (currently minimal)

Publishing path:

- `host` uploads artifacts and prepares release metadata.
- `gh release create` publishes the GitHub Release.
- `publish-homebrew-formula` updates `karsyboy/homebrew-tap` using generated `.rb` files.

### Secrets Used

- `GITHUB_TOKEN`
- `HOMEBREW_TAP_TOKEN`

### Related Config

`dist-workspace.toml` controls cargo-dist behavior:

- dist version
- target matrix
- installer types
- Homebrew tap repo

## Dependabot

`.github/dependabot.yml` currently:

- Updates Cargo dependencies weekly
- Uses grouped dependency PRs
- Labels PRs with `dependencies`
- Leaves GitHub Actions updates disabled (to avoid conflicts with tool-managed workflow versions)

## Maintenance Notes

If you regenerate `release.yml` via cargo-dist, review triggers after regeneration to ensure it remains tag-only.

## Troubleshooting

`release-plz` did not run:

- Confirm push was to `main`.
- Confirm changed files matched `Cargo.toml` or `src/**`.

`release.yml` ran for a PR:

- Verify `release.yml` does not contain a `pull_request` trigger.

`release.yml` did not run after merging release PR:

- Verify `release-plz-release` created and pushed a tag.
- Verify tag matches `**[0-9]+.[0-9]+.[0-9]+*`.

Homebrew update failed:

- Verify `HOMEBREW_TAP_TOKEN` permissions to `karsyboy/homebrew-tap`.
