Skip to content

RELEASE_PROCESS.md

Latest commit

 

History

History
191 lines (142 loc) · 5.73 KB

RELEASE_PROCESS.md

File metadata and controls

191 lines (142 loc) · 5.73 KB
Raw

Release Process

This document describes the secure release process for ftr. This process ensures that all releases are thoroughly tested and validated before artifacts are published.

Overview

The release process has been designed with the following security principles:

  • No release can be created from untested code
  • All releases must go through the full CI pipeline
  • Release artifacts are only built from validated commits on the main branch
  • The process is auditable through PR history

Prerequisites

Before starting a release:

  1. Ensure all planned features and fixes are merged to main
  2. Update CHANGELOG.md with all changes for the release
  3. Ensure the version in Cargo.toml is updated
  4. Run cargo test locally to verify tests pass
  5. Run cargo clippy -- -D warnings to ensure no linting issues

Release Steps

1. Create a Release Branch

# Create a release branch from main
git checkout main
git pull origin main
git checkout -b release-v0.x.y

2. Update Version and Changelog

  1. Update version in Cargo.toml

  2. Update CHANGELOG.md:

    • Move items from [Unreleased] to a new version section
    • Add the release date
    • Update the comparison links at the bottom

  3. Commit the changes:

git add Cargo.toml CHANGELOG.md
git commit -m "Prepare for v0.x.y release"

3. Create a Pull Request

  1. Push the release branch:
git push -u origin release-v0.x.y

  1. Create a PR from release-v0.x.y to main

  2. Ensure all CI checks pass:

    • Tests on all platforms (Linux, macOS, Windows, FreeBSD)
    • Clippy and formatting checks
    • Security audit
    • Documentation builds

  3. Get the PR reviewed and approved by maintainers

4. Merge and Tag

  1. Merge the PR to main
  2. Pull the latest main locally:
git checkout main
git pull origin main
  1. Create and push the release tag:
git tag -a v0.x.y -m "Release v0.x.y

Brief description of major changes

See CHANGELOG.md for full details"

git push origin v0.x.y

5. Monitor the Release Pipeline

When you push the tag, the following automated processes will run:

  1. Release Validation (validate-release.yml):

    • Verifies the tag points to a commit on main
    • Checks that Cargo.toml version matches the tag
    • Runs the full CI suite again
    • Validates that all checks pass

  2. Artifact Building (only if validation passes):

    • Debian packages built for amd64 and arm64
    • Windows binaries built for x64 and ARM64
    • Draft GitHub release created with artifacts

  3. Monitor the Actions tab in GitHub to ensure all workflows succeed

6. Publish the Release

  1. Go to the GitHub Releases page

  2. Find the draft release created by the workflow

  3. Edit the release notes:

    • Add a summary of key changes
    • Include installation instructions
    • Link to the full CHANGELOG
    • Credit contributors

  4. Publish the release (this triggers the crates.io publish and the Homebrew tap update)

7. Verify the Release

After publishing:

  1. Check that the release appears on crates.io
  2. Check that dweekly/homebrew-ftr got the automated formula bump commit
  3. Test installation methods:
    • cargo install ftr
    • brew upgrade ftr (builds from source)
    • Debian package installation
    • Windows binary execution
  4. Update any documentation that references the version

Required Secrets

The release workflow depends on these repository secrets:

  • CARGO_REGISTRY_TOKEN — crates.io API token for cargo publish
  • HOMEBREW_TAP_TOKEN — GitHub personal access token with push access to dweekly/homebrew-ftr (fine-grained PAT scoped to that repo with Contents: read/write). The default GITHUB_TOKEN cannot push cross-repo.

Security Considerations

What the Validation Prevents

  1. Direct tag pushing: Tags must point to commits that exist on main
  2. Untested releases: Full CI must run and pass before artifacts are built
  3. Version mismatches: Tag version must match Cargo.toml version
  4. Bypassing PR process: Commits should go through PR review

Branch Protection Rules

Ensure these GitHub branch protection rules are configured for main:

  • Require pull request reviews before merging
  • Require status checks to pass before merging
  • Require branches to be up to date before merging
  • Include administrators in restrictions
  • Require conversation resolution before merging

Troubleshooting

Release validation fails

If the validation workflow fails:

  1. Check that the tag points to a commit on main
  2. Verify Cargo.toml version matches the tag
  3. Ensure the commit has passed CI (was part of a merged PR)

CI fails on release tag

If CI fails when running on the release tag:

  1. Fix the issue on a new branch
  2. Create a PR to main
  3. After merging, delete the failed tag: git push --delete origin v0.x.y
  4. Start the release process again

Crates.io publish fails

If the crates.io publish fails:

  1. Check the error message in the GitHub Actions log
  2. Common issues:
    • Version already exists on crates.io
    • Missing or invalid API token
    • Cargo.toml metadata issues

Homebrew tap update fails

If the Update Homebrew Tap job fails:

  1. Check that the HOMEBREW_TAP_TOKEN secret exists and has not expired
  2. Fall back to a manual bump in dweekly/homebrew-ftr: update the url and sha256 lines in ftr.rb (download the tarball first, then shasum -a 256 <file> — don't pipe curl into shasum; that produced a wrong hash for v0.6.0) and push

Emergency Release Process

In case of critical security fixes:

  1. Follow the same process but use hotfix-v0.x.y as the branch name
  2. Ensure the fix is minimal and focused
  3. Fast-track the PR review with multiple maintainers
  4. Document the emergency release in CHANGELOG.md