@logickernel/agileflow 0.17.0 → 0.17.1

package/docs/best-practices.md

@@ -1,306 +0,0 @@
-# Best Practices
-
-This guide covers recommended practices for using AgileFlow effectively.
-
-## Decoupled Pipeline Architecture
-
-### Separate Versioning from Build/Deploy
-
-AgileFlow works best with a decoupled architecture:
-
-```
-Versioning Workflow     Release Workflow
-──────────────────     ─────────────────
-on: push to main       on: tag created
-  → AgileFlow            → build
-  → create tag           → deploy
-```
-
-**Benefits:**
-- Clear separation of concerns
-- Each pipeline has one responsibility
-- Easy to rerun builds independently
-
-### Version Workflow (Minimal)
-
-Keep the versioning workflow simple:
-
-```yaml
-# ✅ Good — Focused on versioning only
-name: Version
-on:
-  push:
-    branches: [main]
-jobs:
-  version:
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-      - run: npx @logickernel/agileflow github
-```
-
-### Release Workflow (Complete)
-
-Put build and deploy logic in the tag-triggered workflow:
-
-```yaml
-# ✅ Good — Triggered by tag, handles build/deploy
-name: Release
-on:
-  push:
-    tags: ['v*']
-jobs:
-  build:
-    # Build logic here
-  deploy:
-    # Deploy logic here
-```
-
----
-
-## Commit Message Best Practices
-
-### Use Conventional Commits Consistently
-
-```bash
-# ✅ Good — Clear type and description
-feat(auth): add OAuth2 login support
-fix(api): handle null user ID gracefully
-
-# ❌ Bad — Unclear
-add oauth
-fix bug
-```
-
-### Add Scopes for Organization
-
-```bash
-# ✅ Good — Scoped commits
-feat(auth): implement JWT validation
-fix(api): resolve timeout issue
-docs(readme): add troubleshooting section
-```
-
-### Mark Breaking Changes Properly
-
-```bash
-# ✅ Good — Breaking change marked
-feat!: remove deprecated API endpoints
-
-# ✅ Good — Using footer
-feat: change API format
-
-BREAKING CHANGE: Response uses camelCase keys
-
-# ❌ Bad — Not marked
-feat: remove deprecated endpoints
-```
-
----
-
-## Pipeline Best Practices
-
-### Use Tag as Version
-
-In your release workflow, extract the version from the tag:
-
-**GitHub Actions:**
-```yaml
-- name: Get version
-  run: echo "VERSION=${GITHUB_REF#refs/tags/}" >> $GITHUB_ENV
-
-- name: Build
-  run: docker build -t myapp:$VERSION .
-```
-
-**GitLab CI:**
-```yaml
-build:
-  script:
-    - docker build -t myapp:$CI_COMMIT_TAG .
-  rules:
-    - if: '$CI_COMMIT_TAG =~ /^v/'
-```
-
-### Deploy Same Version Everywhere
-
-```yaml
-# ✅ Good — Same version for all environments
-deploy-staging:
-  script:
-    - kubectl set image deployment/myapp myapp=myapp:$VERSION
-
-deploy-production:
-  script:
-    - kubectl set image deployment/myapp myapp=myapp:$VERSION
-```
-
-### Add Health Checks
-
-```yaml
-deploy:
-  script:
-    - kubectl set image deployment/myapp myapp=myapp:$VERSION
-    - kubectl rollout status deployment/myapp --timeout=300s
-    - ./health-check.sh
-```
-
----
-
-## Version Management Best Practices
-
-### Keep Releases Small
-
-- Small releases reduce risk
-- Frequent releases provide faster feedback
-- Focused changes simplify rollbacks
-
-### Test Before Merging
-
-- Unit tests pass on feature branches
-- Integration tests run before merge
-- Documentation updated with changes
-
-### Plan for Rollbacks
-
-**GitHub Actions:**
-```yaml
-rollback:
-  runs-on: ubuntu-latest
-  steps:
-    - uses: actions/checkout@v4
-      with:
-        fetch-depth: 0
-    - name: Rollback
-      run: |
-        PREVIOUS=$(git describe --tags --abbrev=0 HEAD^)
-        kubectl set image deployment/myapp myapp=myapp:$PREVIOUS
-```
-
-**GitLab CI:**
-```yaml
-rollback:
-  script:
-    - PREVIOUS=$(git describe --tags --abbrev=0 HEAD^)
-    - kubectl set image deployment/myapp myapp=myapp:$PREVIOUS
-  when: manual
-```
-
----
-
-## Security Best Practices
-
-### Protect Tokens
-
-**GitHub:**
-- Use repository secrets (automatically protected)
-- Rotate tokens regularly
-
-**GitLab:**
-- Mark variables as Protected and Masked
-- Use project tokens over personal tokens
-
-### Minimal Permissions
-
-| Platform | Required Permission |
-|----------|---------------------|
-| GitHub | `contents: write` |
-| GitLab | `api` scope, `Maintainer` role |
-
----
-
-## Performance Best Practices
-
-### Shallow Clone for Release Workflow
-
-The release workflow doesn't need full history:
-
-```yaml
-# Versioning — needs full history
-version:
-  steps:
-    - uses: actions/checkout@v4
-      with:
-        fetch-depth: 0  # Full history
-
-# Release — doesn't need history
-build:
-  steps:
-    - uses: actions/checkout@v4
-      # Default shallow clone
-```
-
-### Cache Dependencies
-
-```yaml
-- uses: actions/cache@v4
-  with:
-    path: ~/.npm
-    key: npm-${{ hashFiles('package-lock.json') }}
-```
-
-### Parallel Jobs
-
-```yaml
-# Build jobs run in parallel
-build-backend:
-  runs-on: ubuntu-latest
-build-frontend:
-  runs-on: ubuntu-latest
-```
-
----
-
-## Documentation Best Practices
-
-### Write Meaningful Commit Messages
-
-```bash
-# ✅ Good — Becomes clear release note
-feat(auth): add OAuth2 login with Google and GitHub providers
-
-# ❌ Bad — Poor release note
-feat: add login
-```
-
-### Include Docs in Changes
-
-```bash
-git commit -m "feat(auth): add OAuth2 login
-
-- Implement OAuth2 flow
-- Add configuration documentation
-- Update API reference"
-```
-
----
-
-## Team Best Practices
-
-### Establish Conventions
-
-- Document commit message standards
-- Use commit linting (commitlint, husky)
-- Review commit messages in PRs
-
-### Communicate Releases
-
-```yaml
-notify:
-  script:
-    - |
-      curl -X POST "$SLACK_WEBHOOK" \
-        -d "{\"text\": \"Released $VERSION\"}"
-  rules:
-    - if: '$CI_COMMIT_TAG =~ /^v/'
-```
-
----
-
-## Related Documentation
-
-- [Getting Started](./getting-started.md) — Quick start
-- [Conventional Commits](./conventional-commits.md) — Commit format
-- [Installation Guide](./installation.md) — Setup
-- [Troubleshooting](./troubleshooting.md) — Common issues

package/docs/branching-strategy.md

@@ -1,347 +0,0 @@
-# Branching Strategy
-
-AgileFlow uses a simplified branching strategy that eliminates complexity while maintaining flexibility.
-
-## Overview
-
-Unlike traditional Git workflows with multiple long-lived branches, AgileFlow uses:
-
-- **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
-
-All releases come from main:
-
-- **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
-
-Create focused branches, merge quickly:
-
-- **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-Based Deployments
-
-Deploy versions, not branches:
-
-```
-Version v1.2.3
-    │
-    ├──▶ Staging
-    ├──▶ Production
-    └──▶ Any environment
-```
-
----
-
-## Branch Types
-
-### Feature Branches
-
-For new functionality:
-
-```bash
-git checkout -b feat/user-authentication
-git checkout -b feat/api-rate-limiting
-git checkout -b feat/dark-mode
-```
-
-**When to use:**
-- Adding new features
-- Implementing user stories
-- Creating new endpoints
-
-**Workflow:**
-1. Create from main
-2. Develop with conventional commits
-3. Open pull/merge request
-4. Merge to main → triggers version bump
-
-### Fix Branches
-
-For bug fixes:
-
-```bash
-git checkout -b fix/login-validation
-git checkout -b fix/api-timeout
-git checkout -b fix/memory-leak
-```
-
-**When to use:**
-- Fixing bugs
-- Resolving errors
-- Addressing issues
-
-### Hotfix Branches
-
-For urgent production fixes:
-
-```bash
-git checkout -b hotfix/security-patch
-git checkout -b hotfix/critical-bug
-```
-
-**When to use:**
-- Critical production issues
-- Security vulnerabilities
-- Service outages
-
-**Workflow:**
-1. Create from main
-2. Implement minimal fix
-3. Fast-track review
-4. Merge and deploy immediately
-
-### Refactor Branches
-
-For code improvements:
-
-```bash
-git checkout -b refactor/auth-service
-git checkout -b refactor/database-layer
-```
-
-**When to use:**
-- Improving code structure
-- Reducing technical debt
-- Optimizing performance
-
----
-
-## Branch Lifecycle
-
-### Create
-
-```bash
-# Always start from updated main
-git checkout main
-git pull origin main
-git checkout -b feat/new-feature
-```
-
-### Develop
-
-```bash
-# Make changes with conventional commits
-git commit -m "feat: implement user login"
-git commit -m "test: add login tests"
-git commit -m "docs: update auth documentation"
-```
-
-### Sync
-
-```bash
-# Keep up to date with main
-git checkout main
-git pull origin main
-git checkout feat/new-feature
-git rebase main
-```
-
-### Complete
-
-```bash
-# Push and create pull/merge request
-git push origin feat/new-feature
-```
-
-### Cleanup
-
-```bash
-# After merge
-git checkout main
-git pull origin main
-git branch -d feat/new-feature
-git push origin --delete feat/new-feature
-```
-
----
-
-## Version Management
-
-### Automatic Bumping
-
-AgileFlow determines version bumps from commits:
-
-```bash
-# Patch bump (v1.0.0 → v1.0.1)
-fix: resolve login bug
-
-# Minor bump (v1.0.0 → v1.1.0)
-feat: add user dashboard
-
-# Major bump (v1.0.0 → v2.0.0)
-feat!: remove deprecated API
-
-# No bump
-perf: optimize queries
-refactor: simplify logic
-docs: update README
-chore: update dependencies
-```
-
-### Version Tags
-
-Every merge to main creates a tag:
-
-```bash
-# List versions
-git tag --sort=-version:refname
-
-# View version details
-git show v1.2.3
-
-# Checkout version
-git checkout v1.2.3
-```
-
----
-
-## Environment Management
-
-### Configuration Over Branches
-
-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
-deploy-staging:
-  environment:
-    name: staging
-  variables:
-    DATABASE_URL: "$STAGING_DB_URL"
-
-deploy-production:
-  environment:
-    name: production
-  variables:
-    DATABASE_URL: "$PROD_DB_URL"
-```
-
----
-
-## Best Practices
-
-### Keep Branches Small
-
-```bash
-# ✅ Good — Single purpose
-git checkout -b feat/user-login
-git checkout -b fix/password-validation
-
-# ❌ Bad — Multiple purposes
-git checkout -b feature-and-bugfixes
-```
-
-### Use Conventional Commits
-
-```bash
-# ✅ Good — Clear type and scope
-feat(auth): add OAuth2 support
-fix(api): handle null user ID
-
-# ❌ Bad — No type
-add oauth login
-fix bug
-```
-
-### Rebase Regularly
-
-```bash
-# Weekly sync with main
-git checkout main
-git pull
-git checkout your-branch
-git rebase main
-```
-
-### Clean Up After Merge
-
-```bash
-git branch -d feature-branch
-git push origin --delete feature-branch
-```
-
----
-
-## Migration from Other Workflows
-
-### From GitFlow
-
-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
-
-1. Continue using feature branches
-2. Add AgileFlow for versioning
-3. Deploy versions instead of branches
-
-### From Trunk-Based Development
-
-1. Continue working on main
-2. Use branches for larger changes
-3. Add AgileFlow for versioning
-
----
-
-## Troubleshooting
-
-### Merge Conflicts
-
-- Rebase regularly
-- Keep branches small
-- Resolve during rebase, not merge
-
-### Branch Divergence
-
-- Always start from updated main
-- Rebase instead of merge
-- Delete branches after merge
-
----
-
-## Related Documentation
-
-- [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