Skip to content

RELEASE_AUTOMATION_IMPLEMENTATION.md

Latest commit

 

History

History
292 lines (223 loc) · 8.25 KB

RELEASE_AUTOMATION_IMPLEMENTATION.md

File metadata and controls

292 lines (223 loc) · 8.25 KB
Raw

Release Automation Implementation Summary

This document summarizes the automated release process implementation for TrustLink.

What Was Implemented

1. GitHub Actions Workflows

release-please.yml

  • Trigger: Push to main branch
  • Purpose: Automatically creates Release PRs based on conventional commits
  • Actions:
    • Analyzes commits since last release
    • Determines semantic version bump (major/minor/patch)
    • Creates PR that updates Cargo.toml and CHANGELOG.md
    • Generates changelog from commit messages

publish-release.yml

  • Trigger: GitHub Release published
  • Purpose: Builds and publishes WASM artifacts
  • Actions:
    • Checks out release tag
    • Builds WASM contract
    • Optimizes with soroban contract optimize
    • Uploads both binaries to GitHub Release
    • Creates release summary in GitHub Actions

validate-commits.yml

  • Trigger: PR opened or updated
  • Purpose: Validates commit message format
  • Actions:
    • Checks PR title follows conventional commits
    • Validates commit messages
    • Blocks merge if validation fails

2. Configuration Files

release-please-config.json

  • Configures Release Please behavior
  • Defines changelog sections and commit type mappings
  • Specifies version file (Cargo.toml) and changelog path

.commitlintrc.json

  • Defines commit message validation rules
  • Enforces conventional commits format
  • Specifies allowed types, scopes, and format requirements

.releaserc.json

  • Alternative semantic-release configuration (optional)
  • Provides fallback release automation setup

3. Documentation

RELEASE.md

  • Comprehensive release process documentation
  • Explains how automation works
  • Provides troubleshooting guide
  • Documents manual release procedures

docs/release-workflow.md

  • Detailed workflow guide for contributors and maintainers
  • Commit message format with examples
  • Version bumping scenarios
  • Best practices and troubleshooting

Updated CONTRIBUTING.md

  • Added "Commit Message Conventions" section
  • Explains conventional commits format
  • Provides good/bad examples
  • Documents automated release process

Updated README.md

  • Replaced manual release checklist with automated process
  • Added quick reference for release workflow
  • Links to detailed documentation

4. Pre-commit Hooks

Updated .pre-commit-config.yaml

  • Added commitlint hook for local commit validation
  • Validates messages before commit is created
  • Prevents invalid commits from being pushed

Acceptance Criteria Met

✅ Merging to main with feat/fix commits triggers release PR

  • Release Please automatically creates PR when commits are merged
  • PR is created within minutes of merge
  • No manual action required

✅ Release PR updates version in Cargo.toml and CHANGELOG

  • Version automatically bumped based on commit types
  • CHANGELOG generated from commit messages
  • Grouped by type (Features, Bug Fixes, etc.)

✅ Merging release PR creates GitHub Release

  • Release is created automatically when Release PR is merged
  • Git tag is created with version number
  • Release notes are generated from changelog

✅ WASM artifact attached to release automatically

  • publish-release workflow triggered on release creation
  • Both unoptimized and optimized WASM binaries built
  • Artifacts automatically attached to GitHub Release
  • File sizes and details included in release summary

✅ Commit message conventions documented in CONTRIBUTING.md

  • Comprehensive guide with examples
  • Explains all commit types and their impact
  • Shows good and bad examples
  • Documents scope usage

How It Works

Developer Workflow

  1. Create feature branch:

    git checkout -b feat/your-feature

  2. Commit with conventional format:

    git commit -m "feat(storage): add dual indexing"

  3. Pre-commit validation:

    • Commitlint validates message format
    • Cargo fmt and clippy run
    • Commit is blocked if validation fails

  4. Push and open PR:

    git push origin feat/your-feature

  5. CI validation:

    • Tests run
    • Code quality checks pass
    • Commit message validation passes

  6. Merge to main:

    • Use "Squash and merge" or "Create a merge commit"
    • Do NOT use "Rebase and merge"

Release Automation

  1. Release Please analyzes commits:

    • Reads all commits since last release
    • Determines version bump (major/minor/patch)
    • Generates changelog from commit messages

  2. Release PR is created:

    • Updates Cargo.toml with new version
    • Updates CHANGELOG.md with formatted entries
    • PR is ready for review

  3. Maintainer reviews and merges:

    • Check version bump is correct
    • Review changelog entries
    • Merge Release PR

  4. GitHub Release is created:

    • Git tag is created (e.g., v0.2.0)
    • GitHub Release is published
    • publish-release workflow is triggered

  5. WASM artifacts are built:

    • Workflow checks out release tag
    • Builds WASM contract
    • Optimizes with soroban-cli
    • Uploads both binaries to release

Version Bumping Rules

Commits Version Change Example
feat only Minor 0.1.0 → 0.2.0
fix only Patch 0.1.0 → 0.1.1
feat + fix Minor 0.1.0 → 0.2.0
docs, test, chore only No release —
BREAKING CHANGE footer Major 0.1.0 → 1.0.0

Commit Types

Type Purpose Version Impact
feat New feature Minor
fix Bug fix Patch
docs Documentation None
test Tests None
refactor Code refactoring None
perf Performance improvement Patch
chore Build, CI, dependencies None

Files Created/Modified

Created Files

  • .github/workflows/release-please.yml
  • .github/workflows/publish-release.yml
  • .github/workflows/validate-commits.yml
  • release-please-config.json
  • .commitlintrc.json
  • .releaserc.json
  • RELEASE.md
  • docs/release-workflow.md
  • RELEASE_AUTOMATION_IMPLEMENTATION.md (this file)

Modified Files

  • .pre-commit-config.yaml (added commitlint hook)
  • CONTRIBUTING.md (added commit conventions section)
  • README.md (replaced manual release checklist)

Next Steps

For First Release

  1. Ensure all commits follow conventional format:

    git log --oneline main..origin/main

  2. Merge a commit with feat: or fix: prefix to main

  3. Release Please will create a Release PR within minutes

  4. Review and merge the Release PR

  5. GitHub Release will be created automatically

  6. WASM artifacts will be built and attached

For Team

  1. Update local pre-commit hooks:

    pre-commit install --install-hooks

  2. Read CONTRIBUTING.md for commit conventions

  3. Use conventional commit format for all commits

  4. Monitor Release PRs and merge when ready

Troubleshooting

Release PR not created

  • Check commits follow conventional format
  • Ensure at least one feat or fix commit
  • Check Release Please workflow is enabled

Version bumped incorrectly

  • Review commit messages
  • Check release-please-config.json configuration
  • Verify commit types match expectations

WASM artifacts not attached

  • Check publish-release workflow logs
  • Verify soroban-cli installation succeeded
  • Manually build and attach if needed

Commit validation fails

  • Check commit message format
  • Review .commitlintrc.json rules
  • Fix message and try again

References

Support

For questions or issues with the release process:

  1. Check RELEASE.md for detailed documentation
  2. Review docs/release-workflow.md for workflow guide
  3. See CONTRIBUTING.md for commit conventions
  4. Check GitHub Actions logs for workflow errors
  5. Open an issue on GitHub with details

Implementation Date: March 26, 2026 Status: Ready for use Maintainer: TrustLink Team