From c1ad9ca7d898421f0e3caedf665fb280c9c5a468 Mon Sep 17 00:00:00 2001 From: nicos_backbase Date: Fri, 17 Oct 2025 23:03:12 +0200 Subject: [PATCH] ci: add new release strategy based on release branches --- .github/workflows/release.yml | 23 ++++--- README.md | 1 + docs/release-strategy.md | 126 ++++++++++++++++++++++++++++++++++ 3 files changed, 142 insertions(+), 8 deletions(-) create mode 100644 docs/release-strategy.md diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 5834fbf..32b302f 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -4,6 +4,7 @@ on: push: branches: - main + - 'release/**' paths: - 'src/**' - 'Cargo.toml' @@ -11,10 +12,18 @@ on: pull_request: branches: - main + - 'release/**' paths: - 'src/**' - 'Cargo.toml' - 'Cargo.lock' + workflow_dispatch: + inputs: + release_branch: + description: 'Release branch to build from (e.g., release/1.2)' + required: false + default: 'main' + type: string permissions: contents: write @@ -60,22 +69,20 @@ jobs: - name: Checkout code uses: actions/checkout@v5 with: + ref: ${{ github.event.inputs.release_branch || github.ref }} fetch-depth: 0 - - name: Semantic Version + - name: Semantic version id: version - uses: paulhatch/semantic-version@v5.4.0 + uses: PaulHatch/semantic-version@v5.4.0 with: tag_prefix: "v" - major_pattern: "(MAJOR|BREAKING CHANGE|!:)" - minor_pattern: "(MINOR|feat:|feature:)" - version_format: "${major}.${minor}.${patch}" - change_path: "src" - namespace: "" + major_pattern: "BREAKING CHANGE:" + minor_pattern: "feat:" bump_each_commit: false search_commit_body: true user_format_type: "csv" - enable_prerelease_mode: false + enable_prerelease_mode: true create-release: name: Create Release diff --git a/README.md b/README.md index fbbf271..f575155 100644 --- a/README.md +++ b/README.md @@ -292,6 +292,7 @@ Tip: mount host workspace if operations need local files: - [Release Guide](docs/release.md) - Release conventions - [Semantic Versioning Guide](docs/semantic.md) - How to use semantic versioning +- [Release Strategy](docs/release-strategy.md) - Release branch strategy and feature aggregation ## Alternatives diff --git a/docs/release-strategy.md b/docs/release-strategy.md new file mode 100644 index 0000000..a107d21 --- /dev/null +++ b/docs/release-strategy.md @@ -0,0 +1,126 @@ +# Release Branch Strategy + +This document outlines the release branch strategy for semantic versioning and feature aggregation in the repos project. + +## Overview + +Instead of creating individual releases for each feature or fix, we use release branches to aggregate multiple changes into a single semantic version release. This provides better control over releases and allows for more meaningful version increments. + +## Process + +### 1. Feature Development + +- Develop features and fixes on feature branches as usual +- Merge approved changes to `main` branch +- No releases are automatically created from `main` branch commits + +### 2. Release Preparation + +When ready to create a new release: + +1. **Create a release branch** from `main`: + + ```bash + git checkout main + git pull origin main + git checkout -b release/1.2.0 + ``` + +2. **Push the release branch**: + + ```bash + git push -u origin release/1.2.0 + ``` + +3. **Automatic release creation**: The GitHub Actions workflow will: + - Analyze all commits since the last release + - Determine the appropriate semantic version increment + - Create a new release with aggregated changelog + - Build and upload release artifacts + +### 3. Manual Release Trigger + +You can also manually trigger a release: + +1. Go to the **Actions** tab in GitHub +2. Select the **Release** workflow +3. Click **Run workflow** +4. Optionally specify a release branch (defaults to `main`) + +## Semantic Versioning Rules + +The workflow analyzes commit messages to determine version increments: + +- **Major version** (1.0.0 → 2.0.0): Commits containing `BREAKING CHANGE:` in the body +- **Minor version** (1.0.0 → 1.1.0): Commits with `feat:` prefix +- **Patch version** (1.0.0 → 1.0.1): All other changes (fixes, docs, etc.) + +## Conventional Commits + +To ensure proper semantic versioning, use conventional commit format: + +```text +[optional scope]: + +[optional body] + +[optional footer(s)] +``` + +### Examples + +- **Feature**: `feat: add support for organization-wide repository listing` +- **Fix**: `fix: handle rate limiting in GitHub API calls` +- **Breaking change**: + + ```text + feat: redesign configuration file format + + BREAKING CHANGE: Configuration file format has changed from YAML to JSON. + Users must migrate their existing config files. + ``` + +## Branch Management + +- **`main`**: Latest development code, always deployable +- **`release/*`**: Release preparation branches (e.g., `release/1.2.0`) +- **Feature branches**: Individual feature development (merged to `main`) + +## Workflow Configuration + +The release workflow (`/.github/workflows/release.yml`) is configured with: + +- **`bump_each_commit: false`**: Only increment version once per release +- **`search_commit_body: true`**: Look for breaking changes in commit bodies +- **Release branch triggers**: Automatically trigger on `release/*` branches +- **Manual dispatch**: Allow manual release creation + +## Benefits + +1. **Controlled releases**: Choose when to release and what to include +2. **Meaningful versions**: Aggregate related changes into single releases +3. **Better changelogs**: Comprehensive release notes for multiple features +4. **Flexibility**: Manual and automatic release options +5. **Semantic accuracy**: Proper version increments based on actual impact + +## Example Workflow + +```bash +# Develop features +git checkout -b feature/new-command +# ... develop and test +git checkout main +git merge feature/new-command + +git checkout -b feature/ui-improvements +# ... develop and test +git checkout main +git merge feature/ui-improvements + +# Ready to release +git checkout -b release/1.3.0 +git push -u origin release/1.3.0 +# → GitHub Actions creates v1.3.0 release automatically +``` + +This strategy ensures that releases are intentional, well-tested, and contain meaningful collections of changes rather than incremental updates for every small modification.