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

   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