@logickernel/agileflow 0.4.0 → 0.4.1

package/docs/branching-strategy.md

@@ -1,448 +1,347 @@
-# Branching Strategy Guide
+# Branching Strategy
 
-AgileFlow introduces a simplified, yet powerful branching strategy that eliminates the complexity of traditional multi-branch workflows while maintaining flexibility for development teams.
+AgileFlow uses a simplified branching strategy that eliminates complexity while maintaining flexibility.
 
 ## Overview
 
-Unlike traditional Git workflows that rely on multiple long-lived branches for different environments, AgileFlow uses a **main-branch-first approach** where:
+Unlike traditional Git workflows with multiple long-lived branches, AgileFlow uses:
 
-- **Main branch** is the single source of truth for all releases
-- **Development branches** are short-lived and focused on specific changes
-- **All versions** are created from the same branch, ensuring consistency
-- **Environment management** is handled through configuration, not branches
+- **Main branch** — Single source of truth for all releases
+- **Feature branches** — Short-lived branches for development
+- **Version tags** — Immutable markers for each release
+
+```
+main ─────●─────●─────●─────●───▶
+          │     │     │     │
+          v     v     v     v
+        v1.0.0 v1.0.1 v1.1.0 v1.2.0
+          ▲     ▲
+          │     │
+feat/auth─┘     │
+      fix/crash─┘
+```
+
+---
 
 ## Core Principles
 
 ### 1. Main Branch as Release Source
 
-The main branch (or master) serves as the foundation for all releases:
-
-```mermaid
-graph LR
-    A[main branch] --> B[v1.0.0]
-    A --> C[v1.0.1]
-    A --> D[v1.1.0]
-    A --> E[v2.0.0]
-    
-    F[feature branch] --> A
-    G[bugfix branch] --> A
-    H[hotfix branch] --> A
-```
+All releases come from main:
 
-**Key Benefits:**
-- **Single Version Sequence**: All versions share the same lineage
-- **Consistent History**: Every release builds on the same foundation
-- **Simplified Rollbacks**: Easy to revert to any previous version
-- **No Branch Drift**: All environments can run identical versions
+- **Single version sequence** — v1.0.0, v1.0.1, v1.1.0 all share the same lineage
+- **Consistent history** — Every release builds on the same foundation
+- **Simple rollbacks** — Just deploy a previous version
+- **No branch drift** — All environments run identical code
 
 ### 2. Short-Lived Development Branches
 
-Development branches are created for specific purposes and merged back quickly:
+Create focused branches, merge quickly:
 
-- **Purpose**: Implement features, fix bugs, or make improvements
-- **Lifespan**: Days to weeks, not months
-- **Target**: Always merge back to main when complete
-- **Naming**: Descriptive names that indicate purpose
+- **Purpose** — One feature, one fix, or one improvement
+- **Lifespan** — Days to weeks, not months
+- **Target** — Always merge to main
+- **Naming** — Descriptive prefix (feat/, fix/, etc.)
 
-### 3. Version-Centric Deployments
+### 3. Version-Based Deployments
 
-Instead of branch-based environments, AgileFlow uses version-based deployments:
+Deploy versions, not branches:
 
-```mermaid
-graph LR
-    A[Version v1.2.3] --> B[Staging Environment]
-    A --> C[Production Environment]
-    A --> D[Testing Environment]
-    
-    E[Version v1.2.2] --> F[Previous Production]
 ```
+Version v1.2.3
+    │
+    ├──▶ Staging
+    ├──▶ Production
+    └──▶ Any environment
+```
+
+---
 
-## Branch Types and Naming
+## Branch Types
 
 ### Feature Branches
 
-For new features and enhancements:
+For new functionality:
 
 ```bash
-# Branch naming patterns
 git checkout -b feat/user-authentication
 git checkout -b feat/api-rate-limiting
-git checkout -b feat/dark-mode-ui
+git checkout -b feat/dark-mode
 ```
 
 **When to use:**
-- Adding new functionality
+- Adding new features
 - Implementing user stories
-- Creating new API endpoints
-- Adding new UI components
+- Creating new endpoints
 
 **Workflow:**
-1. Create branch from main
-2. Implement feature with conventional commits
-3. Test thoroughly
-4. Create merge request
-5. Merge to main (triggers version bump)
+1. Create from main
+2. Develop with conventional commits
+3. Open pull/merge request
+4. Merge to main → triggers version bump
 
-### Bug Fix Branches
+### Fix Branches
 
-For fixing bugs and issues:
+For bug fixes:
 
 ```bash
-# Branch naming patterns
-git checkout -b fix/login-validation-error
-git checkout -b fix/api-timeout-issue
+git checkout -b fix/login-validation
+git checkout -b fix/api-timeout
 git checkout -b fix/memory-leak
 ```
 
 **When to use:**
-- Fixing production bugs
-- Resolving test failures
-- Addressing security issues
-- Fixing performance problems
-
-**Workflow:**
-1. Create branch from main
-2. Fix the issue with conventional commits
-3. Add tests to prevent regression
-4. Create merge request
-5. Merge to main (triggers patch version)
+- Fixing bugs
+- Resolving errors
+- Addressing issues
 
 ### Hotfix Branches
 
 For urgent production fixes:
 
 ```bash
-# Branch naming patterns
-git checkout -b hotfix/critical-security-patch
-git checkout -b hotfix/database-connection-fix
-git checkout -b hotfix/urgent-performance-fix
+git checkout -b hotfix/security-patch
+git checkout -b hotfix/critical-bug
 ```
 
 **When to use:**
 - Critical production issues
 - Security vulnerabilities
-- Data corruption issues
 - Service outages
 
 **Workflow:**
-1. Create branch from main
+1. Create from main
 2. Implement minimal fix
-3. Test thoroughly
-4. Create merge request
-5. Merge to main (triggers immediate patch version)
-6. Deploy immediately
+3. Fast-track review
+4. Merge and deploy immediately
 
 ### Refactor Branches
 
-For code improvements and technical debt:
+For code improvements:
 
 ```bash
-# Branch naming patterns
 git checkout -b refactor/auth-service
 git checkout -b refactor/database-layer
-git checkout -b refactor/api-structure
 ```
 
 **When to use:**
 - Improving code structure
 - Reducing technical debt
 - Optimizing performance
-- Modernizing dependencies
 
-**Workflow:**
-1. Create branch from main
-2. Implement refactoring
-3. Ensure all tests pass
-4. Create merge request
-5. Merge to main (triggers patch version)
+---
 
 ## Branch Lifecycle
 
-### 1. Creation
+### Create
 
 ```bash
-# Always start from main
+# Always start from updated main
 git checkout main
 git pull origin main
-
-# Create new branch
 git checkout -b feat/new-feature
 ```
 
-**Best Practices:**
-- Always start from an up-to-date main branch
-- Use descriptive branch names
-- Include type prefix (feat/, fix/, refactor/, etc.)
-
-### 2. Development
+### Develop
 
 ```bash
 # Make changes with conventional commits
-git add .
-git commit -m "feat: implement user authentication system"
-git commit -m "test: add authentication unit tests"
-git commit -m "docs: update API documentation"
+git commit -m "feat: implement user login"
+git commit -m "test: add login tests"
+git commit -m "docs: update auth documentation"
 ```
 
-**Best Practices:**
-- Use conventional commits consistently
-- Make small, focused commits
-- Include tests for new functionality
-- Update documentation as needed
-
-### 3. Integration
+### Sync
 
 ```bash
-# Keep branch up to date with main
+# Keep up to date with main
 git checkout main
 git pull origin main
 git checkout feat/new-feature
 git rebase main
 ```
 
-**Best Practices:**
-- Rebase regularly to avoid conflicts
-- Resolve conflicts during rebase
-- Keep commits clean and logical
-
-### 4. Completion
+### Complete
 
 ```bash
-# Push branch and create merge request
+# Push and create pull/merge request
 git push origin feat/new-feature
 ```
 
-**Best Practices:**
-- Ensure all tests pass
-- Code review completed
-- Documentation updated
-- Ready for production
-
-### 5. Merge and Cleanup
+### Cleanup
 
 ```bash
-# After merge request is approved and merged
+# After merge
 git checkout main
 git pull origin main
 git branch -d feat/new-feature
 git push origin --delete feat/new-feature
 ```
 
-**Best Practices:**
-- Delete local branch after merge
-- Delete remote branch after merge
-- Keep repository clean
+---
 
 ## Version Management
 
-### Automatic Version Bumping
+### Automatic Bumping
 
-AgileFlow automatically determines version bumps based on commit types:
+AgileFlow determines version bumps from commits:
 
 ```bash
-# Patch version (v1.0.0 → v1.0.1)
+# Patch bump (v1.0.0 → v1.0.1)
 fix: resolve login bug
-refactor: improve error handling
-perf: optimize database queries
-build: update dependencies
-ci: fix pipeline configuration
-revert: "feat: add experimental feature"
+perf: optimize queries
+refactor: simplify logic
 
-# No version bump
-docs: update README
-style: fix code formatting
-chore: update dependencies
+# Minor bump (v1.0.0 → v1.1.0)
+feat: add user dashboard
 
-# Minor version (v1.0.0 → v1.1.0)
-feat: add user authentication
-perf: optimize database queries
-
-# Major version (v1.0.0 → v2.0.0)
+# Major bump (v1.0.0 → v2.0.0)
 feat!: remove deprecated API
-BREAKING CHANGE: change database schema
+
+# No bump
+docs: update README
+chore: update dependencies
 ```
 
 ### Version Tags
 
-Every merge to main creates a new version tag:
+Every merge to main creates a tag:
 
 ```bash
-# View all versions
+# List versions
 git tag --sort=-version:refname
 
-# Checkout specific version
-git checkout v1.2.3
-
 # View version details
 git show v1.2.3
+
+# Checkout version
+git checkout v1.2.3
 ```
 
+---
+
 ## Environment Management
 
-### Configuration Over Code
+### Configuration Over Branches
 
-Instead of different branches for different environments, use configuration:
+Use configuration for environment differences, not branches:
 
+**GitHub Actions:**
+```yaml
+deploy-staging:
+  environment: staging
+  env:
+    DATABASE_URL: ${{ secrets.STAGING_DB_URL }}
+
+deploy-production:
+  environment: production
+  env:
+    DATABASE_URL: ${{ secrets.PROD_DB_URL }}
+```
+
+**GitLab CI:**
 ```yaml
-# .gitlab-ci.yml
 deploy-staging:
-  stage: deploy
-  script:
-    - kubectl set image deployment/myapp myapp=myapp:${VERSION}
   environment:
     name: staging
   variables:
-    DATABASE_URL: "staging-db.example.com"
-    LOG_LEVEL: "debug"
+    DATABASE_URL: "$STAGING_DB_URL"
 
 deploy-production:
-  stage: deploy
-  script:
-    - kubectl set image deployment/myapp myapp=myapp:${VERSION}
   environment:
     name: production
   variables:
-    DATABASE_URL: "prod-db.example.com"
-    LOG_LEVEL: "info"
+    DATABASE_URL: "$PROD_DB_URL"
 ```
 
-### Environment-Specific Configs
-
-```yaml
-# config/staging.yaml
-database:
-  host: staging-db.example.com
-  port: 5432
-  ssl: false
-
-# config/production.yaml
-database:
-  host: prod-db.example.com
-  port: 5432
-  ssl: true
-```
+---
 
 ## Best Practices
 
-### 1. Keep Branches Small and Focused
+### Keep Branches Small
 
 ```bash
-# ✅ Good - Single purpose
+# ✅ Good — Single purpose
 git checkout -b feat/user-login
 git checkout -b fix/password-validation
 
-# ❌ Bad - Multiple unrelated changes
+# ❌ Bad — Multiple purposes
 git checkout -b feature-and-bugfixes
 ```
 
-### 2. Use Conventional Commits
+### Use Conventional Commits
 
 ```bash
-# ✅ Good
-feat(auth): add OAuth2 login support
-fix(api): handle null user ID gracefully
-refactor(db): normalize user table schema
+# ✅ Good — Clear type and scope
+feat(auth): add OAuth2 support
+fix(api): handle null user ID
 
-# ❌ Bad
+# ❌ Bad — No type
 add oauth login
 fix bug
-refactor stuff
 ```
 
-### 3. Regular Integration
+### Rebase Regularly
 
 ```bash
-# Rebase weekly to avoid large conflicts
+# Weekly sync with main
 git checkout main
-git pull origin main
+git pull
 git checkout your-branch
 git rebase main
 ```
 
-### 4. Clean Merge History
-
-```bash
-# Use rebase and merge for clean history
-git checkout main
-git pull origin main
-git checkout feature-branch
-git rebase main
-git checkout main
-git merge --ff-only feature-branch
-```
-
-### 5. Immediate Cleanup
+### Clean Up After Merge
 
 ```bash
-# Delete branches after merge
 git branch -d feature-branch
 git push origin --delete feature-branch
 ```
 
-## Migration from Traditional Workflows
+---
 
-### From GitFlow
+## Migration from Other Workflows
 
-If you're currently using GitFlow:
+### From GitFlow
 
-1. **Stop creating release branches** - use main for all releases
-2. **Eliminate develop branch** - work directly from main
-3. **Convert hotfix branches** to hotfix/ branches that merge to main
-4. **Use feature branches** as before, but merge to main
-5. **Implement AgileFlow** for version management
+1. Stop creating release/develop branches
+2. Use main for all releases
+3. Convert hotfix branches to hotfix/ prefix
+4. Let AgileFlow handle versioning
 
 ### From GitHub Flow
 
-If you're using GitHub Flow:
-
-1. **Keep main branch** as your primary branch
-2. **Continue using feature branches** for development
-3. **Add AgileFlow** for automatic versioning
-4. **Use version-based deployments** instead of branch-based
+1. Continue using feature branches
+2. Add AgileFlow for versioning
+3. Deploy versions instead of branches
 
 ### From Trunk-Based Development
 
-If you're using trunk-based development:
+1. Continue working on main
+2. Use branches for larger changes
+3. Add AgileFlow for versioning
 
-1. **Continue working on main** for small changes
-2. **Use feature branches** for larger changes
-3. **Add AgileFlow** for version management
-4. **Implement conventional commits** for automatic versioning
+---
 
 ## Troubleshooting
 
-### Common Issues
-
-**Merge Conflicts**
-- Rebase regularly to minimize conflicts
-- Resolve conflicts during rebase, not merge
-- Keep branches small and focused
-
-**Branch Divergence**
-- Always start from up-to-date main
-- Rebase instead of merge when updating
-- Delete branches after merge
-
-**Version Conflicts**
-- Ensure conventional commits are used
-- Check that AgileFlow is properly configured
-- Verify merge request process
+### Merge Conflicts
 
-### Getting Help
+- Rebase regularly
+- Keep branches small
+- Resolve during rebase, not merge
 
-- **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
+### Branch Divergence
 
-## Conclusion
+- Always start from updated main
+- Rebase instead of merge
+- Delete branches after merge
 
-AgileFlow's branching strategy provides a simplified, yet powerful approach to Git workflow management. By focusing on the main branch as the single source of truth and using short-lived development branches, teams can:
+---
 
-- **Reduce complexity** in their Git workflow
-- **Maintain consistency** across all environments
-- **Automate versioning** through conventional commits
-- **Simplify deployments** with version-based releases
-- **Improve collaboration** with clear branch purposes
+## Related Documentation
 
-This approach transforms complex multi-branch workflows into a streamlined, version-centric process that scales from small teams to large enterprises.
+- [Getting Started](./getting-started.md) — Quick start
+- [Conventional Commits](./conventional-commits.md) — Commit format
+- [Version-Centric CI/CD](./version-centric-cicd.md) — Pipeline methodology
+- [Release Management](./release-management.md) — Managing releases