Skip to content

RELEASING.md

Latest commit

 

History

History
149 lines (106 loc) · 4.16 KB

RELEASING.md

File metadata and controls

149 lines (106 loc) · 4.16 KB

Releasing EnvelopeCLI

This document describes the complete release process for EnvelopeCLI.

Prerequisites

  • cargo and gh CLI tools installed
  • Authenticated with crates.io (cargo login)
  • Authenticated with GitHub (gh auth login)
  • HOMEBREW_TAP_TOKEN secret configured in GitHub repo settings

Release Checklist

1. Prepare the Release

# Ensure you're on master and up to date
git checkout master
git pull origin master

# Run tests locally
cargo test
cargo clippy
cargo fmt --check

2. Update Version Number

Edit Cargo.toml and update the version:

[package]
name = "envelope-cli"
version = "X.Y.Z"  # Update this

Note: The TUI sidebar version display uses env!("CARGO_PKG_VERSION") at compile time, so updating Cargo.toml automatically updates the version shown in the UI. No manual changes needed elsewhere.

Commit the version bump:

git add Cargo.toml Cargo.lock
git commit -m "Bump version to X.Y.Z"
git push origin master

3. Publish to crates.io

# Dry run first
cargo publish --dry-run

# If successful, publish
cargo publish

Verify: https://crates.io/crates/envelope-cli

4. Create Git Tag and Push

git tag vX.Y.Z
git push origin vX.Y.Z

This triggers the GitHub Actions release workflow which:

  • Builds binaries for macOS (Intel + ARM), Linux, Windows
  • Creates GitHub Release with all artifacts
  • Generates shell/PowerShell installers
  • Generates Homebrew formula (attached to release)

5. Monitor Release Workflow

# Watch the release workflow
gh run list --workflow=release.yml --limit 1
gh run watch <run-id>

Verify: https://github.com/KayleeBeyene/EnvelopeCLI/releases

6. Update Homebrew Tap

The release workflow generates envelope-cli.rb but doesn't auto-push to the tap. You must manually update the tap:

# Download the formula from the release
gh release download vX.Y.Z --pattern "envelope-cli.rb" --dir /tmp

# Clone the tap repo
gh repo clone KayleeBeyene/homebrew-tap /tmp/homebrew-tap

# Copy the formula (keep the name as envelope-cli.rb)
cp /tmp/envelope-cli.rb /tmp/homebrew-tap/Formula/envelope-cli.rb

# Commit and push
git -C /tmp/homebrew-tap add -A
git -C /tmp/homebrew-tap commit -m "Update envelope-cli formula to vX.Y.Z"
git -C /tmp/homebrew-tap push origin main

# Cleanup
rm -rf /tmp/homebrew-tap /tmp/envelope-cli.rb

Verify: https://github.com/KayleeBeyene/homebrew-tap

Distribution Channels

After release, users can install via:

Method Command
Cargo cargo install envelope-cli
Homebrew brew tap KayleeBeyene/tap && brew install envelope-cli
Shell script curl -fsSL https://github.com/KayleeBeyene/EnvelopeCLI/releases/latest/download/envelope-cli-installer.sh | sh
PowerShell irm https://github.com/KayleeBeyene/EnvelopeCLI/releases/latest/download/envelope-cli-installer.ps1 | iex
Source git clone ... && cargo install --path .

Troubleshooting

crates.io publish fails

GitHub Actions release fails

  • Check workflow logs: gh run view <run-id> --log-failed
  • Re-run failed workflow: gh run rerun <run-id>

Homebrew tap not updating

  • Ensure HOMEBREW_TAP_TOKEN secret exists with write access to homebrew-tap repo
  • Manually push formula as described in step 6

Version History

Version Date Notes
0.2.6 2025-11-30 ByDate target progress calculation improvements
0.2.5 2025-11-30 TUI terminology updates, account form behavior
0.2.4 2025-11-29 Expected income tracking with budget warnings
0.2.3 2025-11-29 Vim keybindings, unified backup/export restore
0.2.2 2025-11-29 Patch release
0.2.1 2025-11-29 Category group editing, bulk delete, header-less CSV
0.2.0 2025-11-29 XDG-compliant data paths, env var override
0.1.0 2025-11-28 Initial public release