Merge pull request #30 from codcod/28-use-release-branches

ci: add new release strategy based on release branches

Author: codcod

.github/workflows/release.yml

@@ -4,17 +4,26 @@ on:
   push:
     branches:
       - main
+      - 'release/**'
     paths:
       - 'src/**'
       - 'Cargo.toml'
       - 'Cargo.lock'
   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

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
 

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
+<type>[optional scope]: <description>
+
+[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.