lstr-mirror/RELEASE_CHECKLIST.md

# Release Checklist

Use this checklist when preparing a new release of lstr. You can also create a GitHub issue using the "Release" template to track progress.

## Pre-Release

- [ ] All tests passing: `cargo test`
- [ ] No clippy warnings: `cargo clippy`
- [ ] Code is formatted: `cargo fmt --check`
- [ ] CHANGELOG.md updated:
  - [ ] Move items from `[Unreleased]` to new `[X.Y.Z] - YYYY-MM-DD` section
  - [ ] Keep `[Unreleased]` section empty for future changes
  - [ ] Verify changelog entries are accurate and complete
- [ ] Version bumped in `Cargo.toml`
- [ ] Test binary works: `cargo run --release -- examples/sample-directory -L 2`
- [ ] Validation scripts pass: `./scripts/validate-basic.sh`
- [ ] Dry-run the crates.io package: `cargo publish --dry-run`

## Create Release

- [ ] Commit version bump on a release branch off `devel`: `git commit -m "chore: release X.Y.Z"`, PR to `devel`, merge after CI
- [ ] Merge `devel` into `main` (PR or fast-forward) and wait for CI
- [ ] Create version tag on `main`: `git tag vX.Y.Z`
- [ ] Push tag: `git push origin vX.Y.Z`
- [ ] Wait for GitHub Actions workflows to complete (~10-15 minutes)

## Verify Automated Releases

All of the following are now automated via GitHub Actions:

- [ ] **GitHub Release** created at https://github.com/bgreenwell/lstr/releases/tag/vX.Y.Z
  - [ ] All platform binaries present (Linux, macOS, Windows)
  - [ ] Tarballs (.tar.xz) and ZIP archive
  - [ ] MSI installer for Windows
  - [ ] Shell/PowerShell installer scripts
  - [ ] SHA256 checksum files

- [ ] **Homebrew** formula published to [bgreenwell/homebrew-tap](https://github.com/bgreenwell/homebrew-tap)
  - Automated by: `publish-homebrew-formula` job in release.yml

- [ ] **Scoop** manifest published to [bgreenwell/scoop-bucket](https://github.com/bgreenwell/scoop-bucket)
  - Automated by: `.github/workflows/publish-scoop.yml`

- [ ] **crates.io** published at https://crates.io/crates/lstr
  - Manual: `cargo publish` from the tagged commit (not automated)

- [ ] **AUR** package updated at [lstr-bin](https://aur.archlinux.org/packages/lstr-bin)
  - Co-maintainer access granted (see issue #15); `.github/workflows/publish-aur.yml`
    now publishes automatically on tag push. This is its first real run —
    verify it succeeds rather than assuming.
  - `lstr-git` (by bakatrouble) is separately community-maintained; no
    action needed from this pipeline.

- [ ] **WinGet** manifest PR created to [microsoft/winget-pkgs](https://github.com/microsoft/winget-pkgs)
  - Automated by: `.github/workflows/publish-winget.yml`
  - **First release:** `komac update` only works for an existing package;
    submit the initial `bgreenwell.lstr` manifest manually with `komac new`
  - **Note:** PR may require manual merge approval from Microsoft team (1-2 days)

## Test Installations

- [ ] **Homebrew (macOS/Linux)**:
  ```bash
  brew update && brew upgrade lstr
  lstr --version
  ```

- [ ] **Scoop (Windows)**:
  ```powershell
  scoop update && scoop update lstr
  lstr --version
  ```

- [ ] **AUR (Arch Linux)**:
  ```bash
  yay -Syu lstr-bin
  lstr --version
  ```

- [ ] **WinGet (Windows)**:
  ```powershell
  winget upgrade bgreenwell.lstr
  lstr --version
  ```
  **Note:** May take 1-2 days for WinGet PR to be merged

- [ ] **Checksums** - verify a downloaded binary matches its published SHA256:
  ```bash
  curl -LO https://github.com/bgreenwell/lstr/releases/latest/download/lstr-checksums.txt
  curl -LO https://github.com/bgreenwell/lstr/releases/latest/download/lstr-Linux-x86_64.tar.gz
  sha256sum lstr-Linux-x86_64.tar.gz
  grep Linux-x86_64 lstr-checksums.txt
  ```

## Post-Release

- [ ] All automated workflows completed successfully (check GitHub Actions)
- [ ] Close release tracking issue

## Troubleshooting

**GitHub Actions fails:** Verify all secrets are configured: `HOMEBREW_TAP_TOKEN`, `SCOOP_BUCKET_TOKEN`, `CARGO_REGISTRY_TOKEN`, `AUR_SSH_PRIVATE_KEY`, `WINGET_TOKEN`

**AUR automation fails:** Check SSH key is valid (`AUR_SSH_PRIVATE_KEY` secret). Verify `lstr-bin` package exists at aur.archlinux.org.

**WinGet PR not appearing:** Check `.github/workflows/publish-winget.yml` logs. May need to create PR manually with `komac update`.

**Dependabot opens a PR touching `release.yml`:** Don't merge it. `release.yml` is autogenerated by cargo-dist (see its header comment) - its action pins (`actions/upload-artifact`, etc.) are whatever that tool's template expects for the installed cargo-dist version, not something to hand-bump. Close the PR and instead bump the pinned cargo-dist version (currently referenced near the top of `release.yml`, via the `cargo-dist-installer.sh` download) and re-run `dist init`/`dist generate` to regenerate the file consistently.

For detailed workflow information:
- `.github/workflows/release.yml` — main release, Homebrew, crates.io
- `.github/workflows/publish-scoop.yml` — Scoop bucket
- `.github/workflows/publish-aur.yml` — AUR publishing
- `.github/workflows/publish-winget.yml` — WinGet manifests