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

  • Automated by: publish-homebrew-formula job in release.yml

• Scoop manifest published to 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

  • 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

  • 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):

  brew update && brew upgrade lstr
  lstr --version
  

• Scoop (Windows):

  scoop update && scoop update lstr
  lstr --version
  

• AUR (Arch Linux):

  yay -Syu lstr-bin
  lstr --version
  

• WinGet (Windows):

  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:

  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