technicalpickles avatar

release

Use this skill when the user asks to create a release, cut a release, publish a new version, or perf

by technicalpickles|Open Source

Release Skill

This skill guides you through creating a new release for the envsense project.

Release Process Overview

The envsense project uses an automated release workflow that is triggered when:

  1. A version change is detected in Cargo.toml on the main branch
  2. CI tests pass successfully
  3. No git tag exists yet for that version

Step-by-Step Release Instructions

Follow these steps to create a new release via pull request:

1. Verify Current State

Before starting a release, check:

  • All tests pass locally: cargo test --all
  • Code is formatted: cargo fmt --all -- --check
  • Linting passes: cargo clippy --all --locked -- -D warnings
  • Prettier formatting passes: npm run format:check
  • Baseline validation: ./scripts/compare-baseline.sh
  • You're up to date with main branch

2. Determine Version Number

Follow semantic versioning:

  • Patch (0.5.x): Bug fixes, minor changes, no breaking changes
  • Minor (0.x.0): New features, functionality additions, backward compatible
  • Major (x.0.0): Breaking changes (when 1.0+ is reached)

Check current version:

grep '^version = ' Cargo.toml | head -1

Check existing tags:

git tag --sort=-version:refname | head -10

3. Update Version in Cargo.toml

Edit the version field in Cargo.toml:

version = "0.5.1" # Update to new version

Important: This is a workspace project. Only update the root Cargo.toml version field (line ~10).

4. Create Release Branch and PR

Create a release branch with your changes:

git checkout -b release-v0.5.1
git add Cargo.toml
git commit -m "Bump version to 0.5.1"
git push origin release-v0.5.1

5. Create Pull Request

Create a PR with a concise description of the release:

gh pr create --title "Release v0.5.1" --body "Bump version from 0.5.0 to 0.5.1 for patch release."

Or via GitHub UI with a structured description:

## Summary

Bump version from 0.5.0 to 0.5.1 for patch release.

Brief description of what this release includes (new features, bug fixes,
improvements).

Tips for finding changes since last release:

# View commits since last tag
git log $(git describe --tags --abbrev=0)..HEAD --oneline

# View merged PRs since last tag
gh pr list --state merged --limit 50

Example from recent release:

  • PR #60: "Release v0.6.0" - Bump version from 0.5.0 to 0.6.0 for minor release

6. Merge PR to Main

Once the PR is reviewed and approved (or if you have permission, merge directly):

# Merge via command line
gh pr merge --squash

# Or merge via GitHub UI

Note: The project currently uses a lightweight release process. For minor version bumps and non-breaking changes, you can merge your own release PRs after verifying all checks pass.

7. Monitor Automated Release

The automated workflow will:

  1. CI Workflow runs first (.github/workflows/ci.yml):

    • Runs linting (formatting, clippy)
    • Runs prettier checks
    • Runs tests on Ubuntu and macOS
    • Validates baselines

  2. Release Workflow triggers after CI succeeds (.github/workflows/release.yml):

    • Checks if version changed (using scripts/check-version-change.sh)
    • Builds binaries for multiple platforms:
      • Linux x64 (x86_64-unknown-linux-gnu)
      • Linux ARM64 (aarch64-unknown-linux-gnu)
      • macOS Universal (universal-apple-darwin - Intel + Apple Silicon)
    • Signs binaries with cosign (keyless signing)
    • Creates GitHub release with:
      • Release notes (from PR description and auto-generated from commits)
      • Binary artifacts
      • SHA256 checksums
      • Cryptographic signatures (.sig files)
    • Creates and pushes git tag (format: {version}, e.g., 0.5.1)

  3. Validate Release Workflow runs after release is published (.github/workflows/validate-release.yml):

    • Validates all binary signatures using cosign
    • Tests local aqua configuration
    • Reports next steps (aqua registry submission)

8. Monitor Workflow Progress

Check workflow status:

# View recent workflow runs
gh run list --limit 5

# Watch a specific workflow run
gh run watch

# View workflow logs if something fails
gh run view --log

Or visit: https://github.com/technicalpickles/envsense/actions

9. Verify Release

Once complete, verify the release:

# Check the new tag was created
git fetch --tags
git tag --sort=-version:refname | head -5

# View the GitHub release
gh release view 0.5.1  # Use your version number

# Download and test a binary
gh release download 0.5.1 --pattern "*x86_64-unknown-linux-gnu*"

10. Post-Release Tasks (Optional)

After a successful release:

  1. Update aqua registry (if needed):

  2. Announce release (if significant):

    • Update project documentation
    • Post to relevant channels/communities

Binary Naming Convention

Released binaries follow this pattern:

envsense-{version}-{target}

Examples:

  • envsense-0.5.1-x86_64-unknown-linux-gnu (Linux x64)
  • envsense-0.5.1-aarch64-unknown-linux-gnu (Linux ARM64)
  • envsense-0.5.1-universal-apple-darwin (macOS Universal)

Each binary includes:

  • .sha256 checksum file
  • .sig cryptographic signature file
  • .bundle signature bundle file

Testing Releases Locally

Before pushing a release, you can test the build process:

# Run comprehensive release tests
# Note: This will skip Linux targets on macOS and vice versa
./scripts/test-release.sh

# Test specific target build
./scripts/build-target.sh x86_64-unknown-linux-gnu normal

# Test universal macOS build (macOS only)
./scripts/build-target.sh universal-apple-darwin universal

# Verify universal binary contains both architectures (macOS only)
lipo -info target/universal-apple-darwin/release/envsense

# Test binary preparation and validation
./scripts/prepare-binary.sh 0.5.1-test x86_64-unknown-linux-gnu
./scripts/validate-binary.sh dist/envsense-0.5.1-test-x86_64-unknown-linux-gnu

Prerequisites for local testing:

  • Rust toolchain with rustup
  • For Linux builds on macOS: Docker (use ./scripts/dev-docker.sh)
  • For universal macOS builds: macOS with Xcode command line tools

Troubleshooting

Release Workflow Didn't Trigger

Check:

  • CI workflow completed successfully
  • Version in Cargo.toml changed from last tagged release
  • No existing tag with that version exists
  • Push was to main branch

Build Failed

Check:

  • All tests pass locally: cargo test --all
  • Code compiles for all targets
  • Review workflow logs: gh run view --log

Signature Validation Failed

The validate-release workflow might fail if:

  • Cosign signatures weren't created properly
  • Network issues downloading release assets
  • This is usually non-critical; the release itself succeeded

Need to Retry a Release

If you need to fix and retry:

  1. Delete the GitHub release: gh release delete 0.5.1
  2. Delete the git tag locally and remotely: 
    git tag -d 0.5.1
git push origin :refs/tags/0.5.1
  3. Fix issues in a new commit
  4. Restart from step 5 (commit and push)

Schema Version Considerations

Important: The JSON schema version (currently 0.3.0) is separate from the crate version.

When making breaking schema changes:

  1. Update SCHEMA_VERSION in src/schema/main.rs
  2. Update all snapshots: cargo insta accept
  3. Document changes in migration guide: docs/migration-guide.md
  4. Reference CONTRACT.md for compatibility guarantees

Schema changes require:

  • Field renames: Add #[serde(alias = "old_name")]
  • Field removals: Bump schema version
  • New fields: Can be added freely (non-breaking)

Note: Most releases do NOT require schema version changes. Only bump the schema version when making breaking changes to the JSON output structure.

Release Checklist

Use this checklist when performing a release:

Pre-Release Verification:

  • All tests pass locally (cargo test --all)
  • Code is formatted (cargo fmt --all -- --check)
  • Clippy passes (cargo clippy --all --locked -- -D warnings)
  • Prettier passes (npm run format:check)
  • Baseline validation passes (./scripts/compare-baseline.sh)

Version Bump and PR:

  • Version updated in Cargo.toml (root workspace only)
  • Release branch created (e.g., release-v0.6.0)
  • Pull request created with concise description
  • PR merged to main branch

Automated Release Verification:

  • CI workflow completed successfully
  • Release workflow completed successfully
  • Git tag created and pushed (format: 0.6.0)
  • GitHub release published
  • Binaries available for all three targets (Linux x64, Linux ARM64, macOS Universal)
  • Binaries signed with cosign
  • Validation workflow completed (optional)

Post-Release Testing:

  • Release tested (download and run binary from GitHub release)
  • Verify checksums match
  • Verify signature validation works

Key Files and Scripts

Configuration:

GitHub Workflows:

Release Scripts:

  • scripts/check-version-change.sh - Detects version changes and determines if release is needed
  • scripts/build-target.sh - Builds for specific targets (normal or universal)
  • scripts/prepare-binary.sh - Prepares release artifacts with checksums
  • scripts/filter-release-files.sh - Filters artifacts for release
  • scripts/sign-release-binaries.sh - Signs binaries with cosign (keyless)
  • scripts/check-signing-completed.sh - Verifies all signatures were created
  • scripts/validate-signing.sh - Validates signatures for a release
  • scripts/create-release.sh - Extracts changelog content (if exists)
  • scripts/test-release.sh - Comprehensive local release testing

Documentation:

Support

For issues with the release process:

  1. Check GitHub Actions logs
  2. Review recent successful releases for comparison
  3. Consult docs/development.md for detailed documentation
  4. Open an issue if you discover a bug in the release workflow
Download Skill