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

   • Submit PR to https://github.com/aquaproj/aqua-registry
   • Follow validation workflow output for guidance

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:

• Cargo.toml - Version definition (line ~10)
• CONTRACT.md - Schema stability guarantees

GitHub Workflows:

• .github/workflows/ci.yml - CI prerequisite workflow
• .github/workflows/release.yml - Main release workflow
• .github/workflows/validate-release.yml - Post-release validation

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:

• docs/development.md - Development workflow
• docs/migration-guide.md - Schema migration guide

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