@logickernel/agileflow 0.4.0 → 0.4.1

package/docs/release-management.md

@@ -1,498 +1,309 @@
-# Release Management Guide
+# Release Management
 
-AgileFlow revolutionizes release management by automating version generation, creating comprehensive release notes, and ensuring consistent deployments across all environments.
+AgileFlow automates version generation with a decoupled architecture that creates version tags, which then trigger your release pipelines.
 
-## Overview
+## Architecture
 
-Traditional release management often involves:
-- Manual version number management
-- Complex branching strategies for releases
-- Environment-specific deployments
-- Manual release note generation
-- Inconsistent versioning across teams
+```
+Merge to main ──▶ AgileFlow ──▶ Tag v1.2.3 ──▶ Your build/deploy
+```
+
+1. **AgileFlow creates the version tag** — Triggered on merge to main
+2. **Your pipelines handle the release** — Triggered by tag creation
+
+This separation keeps versioning independent from build and deployment.
 
-AgileFlow eliminates these challenges by:
-- **Automatic version generation** based on commit history
-- **Single source of truth** for all releases
-- **Version-centric deployments** across all environments
-- **Automated release notes** from conventional commits
-- **Consistent versioning** for all team members
+---
 
 ## How Version Generation Works
 
 ### Semantic Versioning
 
-AgileFlow follows [Semantic Versioning](https://semver.org/) (SemVer) principles:
+AgileFlow follows [Semantic Versioning](https://semver.org/):
 
 ```
 MAJOR.MINOR.PATCH
-   ^     ^     ^
-   |     |     └── Patch: Bug fixes, documentation, etc.
-   |     └──────── Minor: New features, backward compatible
-   └────────────── Major: Breaking changes
+  │     │     └── Bug fixes, refactors
+  │     └──────── New features
+  └────────────── Breaking changes
 ```
 
-### Automatic Version Bumping
-
-AgileFlow analyzes your commit messages to determine the appropriate version bump:
-
-```bash
-# Patch version (v1.0.0 → v1.0.1)
-fix: resolve login validation error
-refactor: improve error handling
-build: update dependencies
-ci: fix pipeline configuration
-perf: optimize database queries
-revert: "feat: add experimental feature"
-
-# No version bump
-docs: update API documentation
-chore: update issue templates
-style: fix code formatting
-
-# Minor version (v1.0.0 → v1.1.0)
-feat: add user authentication system
-perf: optimize database queries
-feat(api): implement rate limiting
-perf(cache): add Redis caching layer
-
-# Major version (v1.0.0 → v2.0.0)
-feat!: remove deprecated API endpoints
-feat(api)!: change user ID format to UUID
-BREAKING CHANGE: modify database schema
-```
+### Automatic Version Calculation
 
-### Version Calculation Logic
+| Commit Type | Example | Version Bump |
+|-------------|---------|--------------|
+| Breaking | `feat!: remove API` | Major |
+| Feature | `feat: add login` | Minor |
+| Fix | `fix: resolve crash` | Patch |
+| Performance | `perf: optimize` | Patch |
+| No bump | `docs: update README` | None |
 
-1. **Analyze commits** since the last version tag
-2. **Identify commit types** using conventional commit format
-3. **Determine bump level** based on highest impact commit
-4. **Generate new version** by incrementing appropriate component
-5. **Create version tag** and push to repository
+---
 
 ## Release Process
 
-### 1. Development Phase
+### 1. Development
 
-During development, team members work on feature branches:
+Work on feature branches:
 
 ```bash
-# Create feature branch
-git checkout -b feat/user-authentication
-
-# Make changes with conventional commits
-git commit -m "feat: implement basic authentication"
-git commit -m "test: add authentication unit tests"
-git commit -m "docs: update authentication API docs"
-
-# Push and create merge request
-git push origin feat/user-authentication
+git checkout -b feat/user-auth
+git commit -m "feat: implement login flow"
+git push origin feat/user-auth
 ```
 
-### 2. Merge Request Review
+### 2. Merge
 
-Before merging to main:
+Create and merge a pull/merge request to main.
 
-- **Code review** by team members
-- **Automated testing** passes
-- **Documentation** updated
-- **Conventional commits** used consistently
+### 3. Version Creation (Automatic)
 
-### 3. Merge to Main
+AgileFlow runs and creates a tag:
+- Analyzes commits since last version
+- Calculates next version
+- Creates annotated tag with release notes
 
-When the merge request is approved and merged:
+### 4. Release (Your Pipelines)
 
-```bash
-# AgileFlow automatically:
-# 1. Detects the merge to main
-# 2. Analyzes commit history
-# 3. Calculates next version
-# 4. Creates version tag
-# 5. Generates release notes
-# 6. Makes VERSION available to CI/CD
-```
+Tag creation triggers your release workflow:
+- Build artifacts tagged with version
+- Deploy to environments
+- Run tests
 
-### 4. Automated Release
+---
 
-The CI/CD pipeline automatically:
+## Release Workflows
 
+### GitHub Actions
+
+**Release workflow** (`.github/workflows/release.yml`):
 ```yaml
-# .gitlab-ci.yml
-agileflow:
-  stage: version
-  # Generates VERSION variable
+name: Release
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Get version
+        run: echo "VERSION=${GITHUB_REF#refs/tags/}" >> $GITHUB_ENV
+
+      - name: Build
+        run: docker build -t myapp:$VERSION .
+
+  deploy-staging:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: staging
+    steps:
+      - run: kubectl set image deployment/myapp myapp=myapp:$VERSION
+
+  deploy-production:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: production
+    steps:
+      - run: kubectl set image deployment/myapp myapp=myapp:$VERSION
+```
 
+### GitLab CI
+
+```yaml
 build:
   stage: build
   script:
-    - docker build -t myapp:${VERSION} .
-  needs:
-    - agileflow
+    - docker build -t myapp:$CI_COMMIT_TAG .
+  rules:
+    - if: '$CI_COMMIT_TAG =~ /^v/'
 
 deploy-staging:
   stage: deploy
   script:
-    - kubectl set image deployment/myapp myapp=myapp:${VERSION}
-  environment:
-    name: staging
-  needs:
-    - build
-```
+    - kubectl set image deployment/myapp myapp=myapp:$CI_COMMIT_TAG
+  environment: staging
+  rules:
+    - if: '$CI_COMMIT_TAG =~ /^v/'
 
-## Release Notes Generation
+deploy-production:
+  stage: deploy
+  script:
+    - kubectl set image deployment/myapp myapp=myapp:$CI_COMMIT_TAG
+  environment: production
+  when: manual
+  rules:
+    - if: '$CI_COMMIT_TAG =~ /^v/'
+```
 
-### Conventional Commit Release Notes
+---
 
-When conventional commits are detected, AgileFlow generates structured release notes:
+## Release Notes
 
-```text
-v1.2.4
+AgileFlow generates structured release notes from conventional commits:
 
-Features:
-- auth: add OIDC login flow
-- api: implement rate limiting middleware
-- ui: add dark mode toggle
-
-Bug fixes:
-- api: correct null handling in user lookup
-- auth: handle expired refresh tokens gracefully
-- ui: fix button alignment in mobile view
-
-Performance improvements:
-- cache: implement Redis clustering
-- db: optimize user query performance
-- api: add response compression
-
-Documentation:
-- update API authentication guide
-- add deployment troubleshooting section
-- improve contributing guidelines
-
-Tests:
-- add integration tests for auth flow
-- increase test coverage to 85%
-- add performance benchmarks
 ```
-
-### Traditional Commit Release Notes
-
-For commits not following conventional format:
-
-```text
 v1.2.4
-- Merge branch 'feat/user-authentication'
-- Add user login functionality
-- Fix password validation bug
-- Update documentation
-- Add unit tests
-```
 
-## Release Strategies
+### Features
+- auth: add OAuth2 login flow
 
-### Continuous Delivery
+### Bug fixes
+- api: handle null user ID
 
-For teams practicing continuous delivery:
+### Performance
+- cache: implement Redis pooling
+```
 
-```yaml
-# .gitlab-ci.yml
-deploy-staging:
-  stage: deploy
-  script:
-    - kubectl set image deployment/myapp myapp=myapp:${VERSION}
-  environment:
-    name: staging
-  when: always  # Deploy every version to staging
+### View Release Notes
 
-deploy-production:
-  stage: deploy
-  script:
-    - kubectl set image deployment/myapp myapp=myapp:${VERSION}
-  environment:
-    name: production
-  when: manual  # Manual approval for production
+```bash
+git tag -l -n99 v1.2.4
 ```
 
-### Release Trains
+---
 
-For teams using release trains:
+## Initial Development (0.x.x)
 
-```yaml
-# .gitlab-ci.yml
-deploy-staging:
-  stage: deploy
-  script:
-    - kubectl set image deployment/myapp myapp=myapp:${VERSION}
-  environment:
-    name: staging
-  rules:
-    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
-      when: never
-    - if: '$CI_COMMIT_BRANCH == "main"'
-      when: always
+New projects start at v0.0.0:
 
-deploy-production:
-  stage: deploy
-  script:
-    - kubectl set image deployment/myapp myapp=myapp:${VERSION}
-  environment:
-    name: production
-  rules:
-    - if: '$CI_COMMIT_TAG =~ /^v\d+\.\d+\.0$/'  # Only major/minor releases
-      when: manual
-```
+- Features/fixes → Patch bump (0.0.0 → 0.0.1)
+- Breaking changes → Minor bump (0.0.0 → 0.1.0)
 
-### Feature Flags
+---
 
-For teams using feature flags:
+## First Stable Release
 
-```yaml
-# .gitlab-ci.yml
-deploy-staging:
-  stage: deploy
-  script:
-    - kubectl set image deployment/myapp myapp=myapp:${VERSION}
-    - ./scripts/update-feature-flags.sh staging
-  environment:
-    name: staging
+Version 1.0.0 represents first stable release. Create manually:
 
-deploy-production:
-  stage: deploy
-  script:
-    - kubectl set image deployment/myapp myapp=myapp:${VERSION}
-    - ./scripts/update-feature-flags.sh production
-  environment:
-    name: production
-  when: manual
+```bash
+git tag -a v1.0.0 -m "First stable release"
+git push origin v1.0.0
 ```
 
-## Version Management
+This will trigger your release workflow.
+
+---
 
-### Viewing Versions
+## Viewing Releases
 
 ```bash
-# List all versions
+# List versions
 git tag --sort=-version:refname
 
 # View specific version
 git show v1.2.3
 
 # Compare versions
-git diff v1.2.2..v1.2.3
-
-# Checkout specific version
-git checkout v1.2.3
+git log v1.2.2..v1.2.3 --oneline
 ```
 
-### Version Metadata
-
-Each version tag contains rich metadata:
-
-```bash
-# View tag message (release notes)
-git tag -l -n99 v1.2.3
-
-# View tag details
-git show v1.2.3
+---
 
-# View commit hash for version
-git rev-list -n 1 v1.2.3
-```
+## Rollbacks
 
-### Version History
+### Simple Rollback
 
-Track version evolution:
+Redeploy a previous version:
 
 ```bash
-# View version timeline
-git log --oneline --decorate --graph --all
-
-# View commits in specific version
-git log v1.2.2..v1.2.3 --oneline
-
-# View files changed in version
-git diff --name-only v1.2.2..v1.2.3
+kubectl set image deployment/myapp myapp=myapp:v1.2.2
 ```
 
-## Rollback Management
+### Automated Rollback Job
 
-### Simple Rollbacks
+**GitHub Actions:**
+```yaml
+rollback:
+  runs-on: ubuntu-latest
+  steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+    - run: |
+        PREVIOUS=$(git describe --tags --abbrev=0 HEAD^)
+        kubectl set image deployment/myapp myapp=myapp:$PREVIOUS
+```
 
-With AgileFlow's version-centric approach, rollbacks are straightforward:
+**GitLab CI:**
+```yaml
+rollback:
+  script:
+    - PREVIOUS=$(git describe --tags --abbrev=0 HEAD^)
+    - kubectl set image deployment/myapp myapp=myapp:$PREVIOUS
+  when: manual
+```
 
-```bash
-# Rollback to previous version
-git checkout v1.2.2
+---
 
-# Deploy previous version
-kubectl set image deployment/myapp myapp=myapp:v1.2.2
-```
+## Release Strategies
 
-### Automated Rollback
+### Continuous Delivery
 
-Implement automated rollback in your CI/CD:
+Auto-deploy to staging, manual to production:
 
 ```yaml
-# .gitlab-ci.yml
-deploy-production:
-  stage: deploy
-  script:
-    - kubectl set image deployment/myapp myapp=myapp:${VERSION}
-    - ./scripts/health-check.sh
-  environment:
-    name: production
-  when: manual
+deploy-staging:
+  # Runs automatically on tag
 
-rollback-production:
-  stage: deploy
-  script:
-    - PREVIOUS_VERSION=$(git describe --abbrev=0 --tags v${VERSION%.*}.$((10#${VERSION##*.} - 1)))
-    - kubectl set image deployment/myapp myapp=myapp:${PREVIOUS_VERSION}
-  environment:
-    name: production
+deploy-production:
   when: manual
-  allow_failure: true
 ```
 
-## Release Communication
-
-### Release Announcements
+### Version-Based Gates
 
-Automate release announcements:
+Only deploy certain version types:
 
 ```yaml
-# .gitlab-ci.yml
-announce-release:
-  stage: deploy
-  script:
-    - |
-      cat << EOF | curl -X POST -H 'Content-Type: application/json' \
-        -d @- $SLACK_WEBHOOK_URL
-      {
-        "text": "🚀 New Release: ${VERSION}",
-        "attachments": [{
-          "title": "Release Notes",
-          "text": "$(git tag -l -n99 ${VERSION})",
-          "color": "good"
-        }]
-      }
-      EOF
-  needs:
-    - agileflow
-  when: manual
+deploy-production:
+  rules:
+    # Only minor/major versions
+    - if: '$CI_COMMIT_TAG =~ /^v\d+\.\d+\.0$/'
 ```
 
-### Release Documentation
+---
 
-Generate release documentation:
+## Release Communication
+
+### Notifications
 
 ```yaml
-# .gitlab-ci.yml
-generate-release-docs:
-  stage: deploy
+notify:
   script:
-    - mkdir -p releases
     - |
-      cat > "releases/${VERSION}.md" << EOF
-      # Release ${VERSION}
-      
-      ## Changes
-      $(git tag -l -n99 ${VERSION})
-      
-      ## Deployment
-      - Staging: ${CI_ENVIRONMENT_URL}
-      - Production: Manual deployment required
-      
-      ## Rollback
-      Previous version: $(git describe --abbrev=0 --tags v${VERSION%.*}.$((10#${VERSION##*.} - 1)))
-      EOF
-    - git add releases/
-    - git commit -m "docs: add release documentation for ${VERSION}"
-    - git push origin main
-  needs:
-    - agileflow
+      curl -X POST "$SLACK_WEBHOOK" \
+        -d "{\"text\": \"Released $CI_COMMIT_TAG\"}"
+  rules:
+    - if: '$CI_COMMIT_TAG =~ /^v/'
 ```
 
-## Best Practices
-
-### 1. Consistent Commit Messages
+### GitHub Releases
 
-```bash
-# ✅ Good - Clear and consistent
-feat(auth): add OAuth2 login support
-fix(api): handle null user ID gracefully
-docs: update installation guide
-
-# ❌ Bad - Inconsistent and unclear
-add oauth
-fix bug
-update docs
+```yaml
+- uses: softprops/action-gh-release@v1
+  with:
+    tag_name: ${{ github.ref_name }}
+    generate_release_notes: true
 ```
 
-### 2. Small, Focused Releases
-
-- **Keep releases small** and focused on specific features
-- **Release frequently** to reduce risk
-- **Test thoroughly** before merging to main
-- **Document breaking changes** clearly
-
-### 3. Environment Consistency
-
-- **Deploy the same version** to all environments
-- **Use configuration** for environment differences
-- **Test in staging** before production
-- **Monitor deployments** for issues
-
-### 4. Version Tagging
-
-- **Never manually create** version tags
-- **Let AgileFlow handle** all versioning
-- **Use conventional commits** for automatic versioning
-- **Review release notes** before deployment
-
-### 5. Rollback Planning
-
-- **Plan rollback procedures** in advance
-- **Test rollback processes** regularly
-- **Document rollback steps** for each environment
-- **Monitor system health** after deployments
+---
 
-## Troubleshooting
-
-### Common Issues
-
-**Version Not Generated**
-- Check that conventional commits are used
-- Verify AgileFlow is properly configured
-- Ensure merge request process is followed
-- Check CI/CD pipeline logs
-
-**Release Notes Empty**
-- Verify commit message format
-- Check conventional commit types
-- Ensure commits are properly merged
-- Review AgileFlow configuration
-
-**Deployment Issues**
-- Verify VERSION variable is available
-- Check job dependencies in pipeline
-- Ensure environment configuration is correct
-- Review deployment scripts
-
-### Getting Help
-
-- **Documentation**: Check other guides in this documentation
-- **Examples**: Review the getting started guide
-- **Community**: Join discussions in the community forum
-- **Issues**: Open an issue in the project repository
+## Best Practices
 
-## Conclusion
+1. **Use conventional commits** — For accurate versioning
+2. **Keep releases small** — Easier to debug and rollback
+3. **Test in staging first** — Before production
+4. **Document breaking changes** — Clear for users
+5. **Plan rollbacks** — Have procedures ready
 
-AgileFlow's release management approach transforms complex, manual release processes into automated, consistent workflows. By leveraging conventional commits and version-centric deployments, teams can:
+---
 
-- **Automate version generation** and release note creation
-- **Maintain consistency** across all environments
-- **Simplify rollbacks** with version-based deployments
-- **Improve collaboration** with clear release communication
-- **Reduce risk** through frequent, small releases
+## Related Documentation
 
-This approach scales from small teams to large enterprises, providing the structure and automation needed for modern software delivery while maintaining the flexibility teams require for effective development.
+- [Getting Started](./getting-started.md) — Quick start
+- [Conventional Commits](./conventional-commits.md) — Commit format
+- [Version-Centric CI/CD](./version-centric-cicd.md) — Methodology
+- [Best Practices](./best-practices.md) — Recommendations