@logickernel/agileflow 0.1.0

package/README.md

@@ -0,0 +1,289 @@
+![AgileFlow icon](./media/agileflow_icon.svg)
+
+# AgileFlow
+
+In today's fast-paced software development landscape, maintaining clarity, consistency, and efficiency in the release process is essential. AgileFlow is a streamlined yet powerful versioning system, branching strategy, and CI/CD tool designed for software teams of all sizes and projects of any scale.
+
+AgileFlow enforces Semantic Versioning and integrates a robust branching strategy for development and deployment. It seamlessly works with GitLab CI pipelines to ensure a structured, efficient, and predictable development lifecycle. **All versions are calculated from the main branch's commit history**, ensuring consistent versioning and release notes. Whether for small projects or large-scale deployments, AgileFlow is an indispensable tool that simplifies versioning and release management.
+
+![AgileFlow workflow example diagram](./media/diagram.jpg)
+
+AgileFlow works integrated with the CI/CD engine to **automatically create a new version** every time there's a merge into the main branch, incrementing the patch number based on the latest identifiable version in the repository.
+
+# Installation
+
+## GitLab CI
+
+AgileFlow integrates with GitLab CI to automate version tagging. Add the following line at the top of `.gitlab-ci.yml`:
+
+```yml
+include:
+  - remote: https://code.logickernel.com/kernel/agileflow/-/raw/main/templates/AgileFlow.gitlab-ci.yml
+```
+
+Introducing a simple workflow in which an environment variable $VERSION is available.
+
+**Learn More**: [Complete Installation Guide](./docs/installation.md) - Step-by-step setup for different platforms
+
+> [!NOTE]
+> AgileFlow uses the GitLab API to create version tags remotely, eliminating the need for repository write permissions. You'll need to configure the `AGILEFLOW_TOKEN` environment variable with API access. See the [Installation Guide](./docs/installation.md) for complete setup instructions.
+
+
+# Core Principles
+
+## Main Branch Strategy
+
+The main branch is the core of the AgileFlow framework. It serves as the single source of truth for all releases and versioning.
+
+**Key Benefits:**
+- **Single Version Sequence**: All versions (v1.0.0, v1.0.1, v1.1.0, etc.) are created from the same branch
+- **Simplified Workflow**: No need to manage multiple release branches
+- **Consistent History**: All releases share the same commit history and lineage
+- **Easy Rollbacks**: Simple to revert to any previous version since all versions are on the same branch
+
+**Version Management:**
+- Patch versions (v1.0.0 → v1.0.1) are automatically incremented on each merge to main
+- Minor versions (v1.0.0 → v1.1.0) are created by merging significant features
+- Major versions (v1.0.0 → v2.0.0) are created for breaking changes
+
+**Learn More**: [Branching Strategy Guide](./docs/branching-strategy.md) - Complete guide to AgileFlow's branching approach
+
+## Development Branches
+
+Development branches are used for feature additions and bug fixes. They branch off the main branch and merge back into it when ready. Consider using expressive names depending on their purpose, e.g.: `dev/*`, `feat/*`, `fix/*`, and `hotfix/*`.
+
+After the contribution is ready, the development branch is merged into main, preferably using a [Pull Request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) a [Merge Request](https://docs.gitlab.com/ee/user/project/merge_requests/) or similar.
+
+**Learn More**: [Getting Started Guide](./docs/getting-started.md) - Quick start for new AgileFlow users
+
+# Version-Centric CI/CD Approach
+
+AgileFlow introduces a revolutionary approach to CI/CD that prioritizes **version management over environment-based deployments**. This paradigm shift eliminates the complexity of managing multiple deployment branches and environments, replacing them with a streamlined, version-focused workflow.
+
+## What Makes AgileFlow Different?
+
+- **Version-Centric**: Every deployment, test, and operation is performed on well-identified versions
+- **Simplified Pipeline**: Just 6 focused stages (version, test, build, deploy, e2e, clean)
+- **Eliminates Environment Drift**: All environments run identical versions
+- **Predictable Deployments**: Every deployment uses a well-identified, immutable version
+- **Simple Rollbacks**: Rollback to any previous version with confidence
+
+## Pipeline Stages
+
+Your pipeline consists of 6 focused stages that work together seamlessly:
+
+1. **Version** - AgileFlow generates semantic versions automatically
+2. **Test** - Run tests against the source code before building
+3. **Build** - Create versioned artifacts using the generated version
+4. **Deploy** - Deploy the same version everywhere (staging, production, etc.)
+5. **E2E** - Run end-to-end tests against the deployed version
+6. **Clean** - Cleanup temporary resources and artifacts
+
+**Learn More**: [Version-Centric CI/CD Deep Dive](./docs/version-centric-cicd.md) - Comprehensive guide to AgileFlow's revolutionary CI/CD paradigm
+
+# Conventional Commits
+
+Conventional Commits encode the intent of a change in the commit subject so that humans (and tools) can generate clear release notes and version bumps.
+
+## Commit Format
+
+```text
+type[!]?(scope)?: description
+
+[optional body]
+
+[optional footer(s)]
+```
+
+## Key Commit Types
+
+- **feat** - New features (minor version bump)
+- **fix** - Bug fixes (patch version bump)
+- **perf** - Performance improvements (patch version bump)
+- **refactor** - Code refactoring (patch version bump)
+- **build** - Build system changes (patch version bump)
+- **ci** - CI/CD changes (patch version bump)
+- **revert** - Revert previous commits (patch version bump)
+- **docs** - Documentation updates (no version bump)
+- **test** - Test additions/changes (patch version bump)
+- **style** - Code style changes (no version bump)
+- **chore** - Maintenance tasks (no version bump)
+- **!** - Breaking changes (major version bump)
+
+## Example Commits
+
+```text
+feat(auth): add OIDC login flow
+fix(api): correct null handling in user lookup
+perf(cache)!: switch to Redis cluster
+docs: update README with usage examples
+```
+
+**Learn More**: [Conventional Commits Guide](./docs/conventional-commits.md) - Complete guide to commit message formatting and types
+
+# Release Management
+
+## Automatic Version Generation
+
+AgileFlow automatically analyzes your commit history and determines the next semantic version based on conventional commits. Each merge to main triggers a new version:
+
+- **Patch versions** (v1.0.0 → v1.0.1) for bug fixes, performance improvements, build changes, CI changes, refactors, reverts, and tests
+- **Minor versions** (v1.0.0 → v1.1.0) for new features
+- **Major versions** (v1.0.0 → v2.0.0) for breaking changes
+
+## Initial Versioning (0.x.x)
+
+When you first start using AgileFlow, the system begins at **v0.0.0** and automatically increments versions based on your commits:
+
+- **Patch versions** (v0.0.0 → v0.0.1) for features, bug fixes, and other changes
+- **Minor versions** (v0.0.0 → v0.1.0) for breaking changes
+
+This allows you to develop and iterate while AgileFlow tracks your progress automatically.
+
+## Version 1.0.0 - Your First Stable Release
+
+**Version 1.0.0 is a significant milestone** that represents your first stable, production-ready release. This version should be **created manually** when your team decides the software is ready for its first stable release.
+
+To create version 1.0.0:
+
+```bash
+# Create the tag manually
+git tag -a v1.0.0 -m "First stable release"
+
+# Push the tag to remote
+git push origin v1.0.0
+```
+
+After v1.0.0 is created, AgileFlow will continue to automatically generate subsequent versions (v1.0.1, v1.1.0, v2.0.0, etc.) based on your commit history.
+
+> [!NOTE]
+> The transition to 1.0.0 is a deliberate decision that should be made by your team when you're ready to declare API stability and production readiness. AgileFlow will not automatically create 1.0.0 from 0.x.x versions.
+
+## Release Notes
+
+AgileFlow generates comprehensive release notes by grouping changes according to their intent:
+
+```text
+v1.2.4
+
+Features:
+- auth: add OIDC login flow
+
+Bug fixes:
+- api: correct null handling in user lookup
+
+Performance improvements:
+- cache: optimize Redis connection pooling
+
+Build system:
+- update webpack to v5
+- upgrade React to 18.2.0
+
+CI:
+- fix pipeline configuration
+
+Refactors:
+- simplify authentication logic
+
+Tests:
+- add integration tests for auth flow
+- increase test coverage to 85%
+
+Reverts:
+- "feat: add experimental feature"
+
+Documentation:
+- update README with usage examples
+```
+
+**Learn More**: [Release Management Guide](./docs/release-management.md) - How to manage releases and versions effectively
+
+# GitLab CI Integration
+
+## Template Usage
+
+Include the AgileFlow template in your `.gitlab-ci.yml`:
+
+```yaml
+include:
+  - local: templates/AgileFlow.gitlab-ci.yml
+
+# Your custom jobs using the VERSION variable
+build:
+  stage: build
+  script:
+    - docker build -t myapp:${VERSION} .
+    - docker push myapp:${VERSION}
+  needs:
+    - agileflow
+```
+
+> [!NOTE]
+> If you prefer to use the remote template, you can use:
+> ```yaml
+> include:
+>   - remote: https://code.logickernel.com/kernel/agileflow/-/raw/main/templates/AgileFlow.gitlab-ci.yml
+> ```
+
+## Key Benefits
+
+- **Automated Versioning**: The `agileflow` job generates versions automatically
+- **VERSION Variable**: Available to all subsequent stages
+- **Consistent Deployments**: Deploy the same version everywhere
+- **Simplified Rollbacks**: Rollback to any previous version with confidence
+
+**Learn More**: [GitLab CI Template Reference](./docs/gitlab-ci-template.md) - Complete reference for the AgileFlow GitLab CI template
+
+# Getting Started
+
+## Quick Setup (5 minutes)
+
+1. **Include the template** in your `.gitlab-ci.yml`
+2. **Add your first job** using the `${VERSION}` variable
+3. **Commit and push** - AgileFlow automatically generates versions
+
+## Next Steps
+
+- Add deployment jobs for staging and production
+- Implement testing against deployed versions
+- Customize for multiple services
+- Set up environment-specific configurations
+
+**Learn More**: [Getting Started Guide](./docs/getting-started.md) - Step-by-step setup and examples
+
+# Advanced Topics
+
+## Migration from Traditional CI/CD
+
+If you're currently using a traditional branch-based approach:
+
+1. **Start with AgileFlow** - Include the template and let it generate versions
+2. **Gradually simplify** - Remove environment-specific branches over time
+3. **Update deployments** - Modify scripts to use `${VERSION}` variable
+4. **Standardize testing** - Run tests against the deployed version
+5. **Document changes** - Update runbooks to reference versions
+
+## Best Practices
+
+- Always use the `${VERSION}` variable from AgileFlow
+- Deploy the same version to all environments
+- Test against deployed versions, not source code
+- Use conventional commits for automatic versioning
+- Keep deployment scripts identical across environments
+
+**Learn More**: [Advanced Topics](./docs/README.md#advanced-topics) - Migration guides, best practices, and troubleshooting
+
+# Documentation
+
+For comprehensive guides and detailed explanations, see our [documentation folder](./docs/README.md).
+
+## Quick Navigation
+
+- **New to AgileFlow?** Start with [Getting Started](./docs/getting-started.md)
+- **Want to understand the approach?** Read [Version-Centric CI/CD](./docs/version-centric-cicd.md)
+- **Ready to implement?** Follow [GitLab CI Template Reference](./docs/gitlab-ci-template.md)
+- **Need help?** Check [Troubleshooting](./docs/troubleshooting.md)
+
+---
+
+**Ready to transform your CI/CD?** Start with AgileFlow today and experience the benefits of a version-centric, streamlined deployment process! 🚀

package/bin/agileflow

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+'use strict';
+
+require('../src/index.js');

package/docs/README.md

@@ -0,0 +1,46 @@
+# AgileFlow Documentation
+
+Welcome to the AgileFlow documentation! This folder contains detailed guides and explanations for different aspects of the AgileFlow system.
+
+## Quick Navigation
+
+- **New to AgileFlow?** Start with [Getting Started](./getting-started.md)
+- **Want to understand the approach?** Read [Version-Centric CI/CD](./version-centric-cicd.md)
+- **Ready to install?** Follow [Installation & Setup](./installation.md)
+- **Need help?** Check [Troubleshooting](./troubleshooting.md)
+
+## Available Documentation
+
+### Core Concepts
+- **[Version-Centric CI/CD Approach](./version-centric-cicd.md)** - Comprehensive guide to AgileFlow's revolutionary CI/CD paradigm
+- **[Installation & Setup](./installation.md)** - Step-by-step installation instructions for different platforms
+- **[Conventional Commits](./conventional-commits.md)** - Detailed guide to commit message formatting and types
+
+### User Guides
+- **[Getting Started](./getting-started.md)** - Quick start guide for new AgileFlow users
+- **[Branching Strategy](./branching-strategy.md)** - Complete guide to AgileFlow's branching approach
+- **[Release Management](./release-management.md)** - How to manage releases and versions effectively
+
+### Reference
+- **[GitLab CI Template](./gitlab-ci-template.md)** - Complete reference for the AgileFlow GitLab CI template
+- **[CLI Reference](./cli-reference.md)** - Command-line interface documentation
+- **[Configuration](./configuration.md)** - Configuration options and environment variables
+
+### Advanced Topics
+- **[Migration Guide](./migration-guide.md)** - How to transition from traditional CI/CD approaches
+- **[Best Practices](./best-practices.md)** - Recommended practices and patterns
+- **[Troubleshooting](./troubleshooting.md)** - Common issues and solutions
+
+## Contributing to Documentation
+
+We welcome contributions to improve our documentation! Please:
+
+1. Follow the existing style and tone
+2. Use clear, concise language
+3. Include practical examples where helpful
+4. Test any code examples or commands
+5. Submit changes via merge requests
+
+## External Resources
+
+- [Main README](../README.md) - Project overview and quick start

package/docs/best-practices.md

@@ -0,0 +1,339 @@
+# Best Practices Guide
+
+This guide provides recommended practices and patterns for using AgileFlow effectively in your development workflow.
+
+## Commit Message Best Practices
+
+### 1. Use Conventional Commits Consistently
+
+```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
+```
+
+### 2. Add Scopes for Better Organization
+
+```bash
+# ✅ Good - Scoped commits
+feat(auth): implement JWT token validation
+fix(api): resolve user lookup timeout
+docs(readme): add troubleshooting section
+
+# ❌ Bad - No scope
+feat: implement JWT token validation
+fix: resolve user lookup timeout
+docs: add troubleshooting section
+```
+
+### 3. Write Clear, Descriptive Messages
+
+```bash
+# ✅ Good - Clear description
+feat(auth): add two-factor authentication with SMS
+fix(api): handle database connection failures gracefully
+docs: add comprehensive API reference
+
+# ❌ Bad - Vague description
+feat: add 2FA
+fix: fix bug
+docs: update docs
+```
+
+### 4. Use Breaking Change Indicators Properly
+
+```bash
+# ✅ Good - Breaking changes clearly marked
+feat!: remove deprecated API endpoints
+feat(auth)!: change user ID format to UUID
+BREAKING CHANGE: modify database schema
+
+# ❌ Bad - Breaking changes not marked
+feat: remove deprecated API endpoints
+feat(auth): change user ID format to UUID
+```
+
+## Pipeline Configuration Best Practices
+
+### 1. Always Use the VERSION Variable
+
+```yaml
+# ✅ Good - Uses VERSION from AgileFlow
+build:
+  stage: build
+  script:
+    - docker build -t myapp:${VERSION} .
+    - docker push myapp:${VERSION}
+
+# ❌ Bad - Hardcoded or branch-based tagging
+build:
+  stage: build
+  script:
+    - docker build -t myapp:latest .
+    - docker build -t myapp:${CI_COMMIT_REF_SLUG} .
+```
+
+### 2. Proper Stage Dependencies
+
+```yaml
+# ✅ Good - Clear dependency chain
+deploy:
+  stage: deploy
+  needs:
+    - build
+
+# ❌ Bad - No dependencies specified
+deploy:
+  stage: deploy
+```
+
+### 3. Environment-Specific Deployments
+
+```yaml
+# ✅ Good - Same version, different environments
+deploy-staging:
+  environment:
+    name: staging
+
+deploy-production:
+  environment:
+    name: production
+  when: manual
+```
+
+### 4. Consistent Testing
+
+```yaml
+# ✅ Good - Test against deployed version
+test:
+  stage: test
+  script:
+    - ./run-tests.sh --version ${VERSION}
+  needs:
+    - deploy-staging
+```
+
+## Version Management Best Practices
+
+### 1. Keep Releases Small and Focused
+
+- **Small releases** reduce risk and make debugging easier
+- **Frequent releases** provide faster feedback
+- **Focused changes** make rollbacks more predictable
+
+### 2. Test Thoroughly Before Merging
+
+- **Unit tests** should pass on feature branches
+- **Integration tests** should run before merge
+- **Documentation** should be updated with changes
+
+### 3. Use Feature Flags for Large Changes
+
+```yaml
+# ✅ Good - Feature flag for gradual rollout
+deploy:
+  stage: deploy
+  script:
+    - kubectl set image deployment/myapp myapp=myapp:${VERSION}
+    - kubectl patch deployment/myapp -p '{"spec":{"template":{"metadata":{"annotations":{"feature-flag/new-auth":"enabled"}}}}}'
+```
+
+### 4. Monitor Deployments
+
+```yaml
+# ✅ Good - Health checks after deployment
+deploy:
+  stage: deploy
+  script:
+    - kubectl set image deployment/myapp myapp=myapp:${VERSION}
+    - kubectl rollout status deployment/myapp --timeout=300s
+    - ./health-check.sh
+```
+
+## Security Best Practices
+
+### 1. Secure Environment Variables
+
+```yaml
+# ✅ Good - Protected and masked variables
+variables:
+  AGILEFLOW_TOKEN: $AGILEFLOW_TOKEN  # Protected and masked
+  GITLAB_USER_NAME: "AgileFlow Bot"  # Not sensitive
+
+# ❌ Bad - Exposed sensitive information
+variables:
+  AGILEFLOW_TOKEN: "glpat-xxxxxxxxxxxxxxxxxxxx"
+```
+
+### 2. Minimal Token Permissions
+
+- **Use project tokens** instead of personal tokens when possible
+- **Limit token scope** to only required permissions
+- **Regular token rotation** for security
+
+### 3. Environment Isolation
+
+```yaml
+# ✅ Good - Environment-specific configurations
+deploy-staging:
+  environment:
+    name: staging
+  variables:
+    DATABASE_URL: $STAGING_DATABASE_URL
+
+deploy-production:
+  environment:
+    name: production
+  variables:
+    DATABASE_URL: $PRODUCTION_DATABASE_URL
+```
+
+## Performance Best Practices
+
+### 1. Optimize Build Times
+
+```yaml
+# ✅ Good - Cached dependencies
+build:
+  stage: build
+  cache:
+    key: ${CI_COMMIT_REF_SLUG}
+    paths:
+      - node_modules/
+      - .cache/
+  script:
+    - npm ci --cache .npm --prefer-offline
+    - npm run build
+```
+
+### 2. Parallel Job Execution
+
+```yaml
+# ✅ Good - Parallel builds for multiple services
+build-backend:
+  stage: build
+  script:
+    - docker build -t backend:${VERSION} ./backend
+
+build-frontend:
+  stage: build
+  script:
+    - docker build -t frontend:${VERSION} ./frontend
+
+# Both jobs can run in parallel
+```
+
+### 3. Efficient Artifact Management
+
+```yaml
+# ✅ Good - Selective artifacts
+build:
+  stage: build
+  artifacts:
+    paths:
+      - dist/
+      - build/
+    expire_in: 1 week
+    when: on_success
+```
+
+## Monitoring and Observability
+
+### 1. Pipeline Visibility
+
+```yaml
+# ✅ Good - Clear job names and descriptions
+build-production:
+  stage: build
+  description: "Build production artifacts with version ${VERSION}"
+  script:
+    - echo "Building version ${VERSION}"
+```
+
+### 2. Deployment Tracking
+
+```yaml
+# ✅ Good - Track deployment status
+deploy:
+  stage: deploy
+  script:
+    - kubectl set image deployment/myapp myapp=myapp:${VERSION}
+    - echo "Deployed ${VERSION} at $(date)" >> deployment.log
+```
+
+### 3. Error Reporting
+
+```yaml
+# ✅ Good - Comprehensive error handling
+deploy:
+  stage: deploy
+  script:
+    - |
+      if ! kubectl set image deployment/myapp myapp=myapp:${VERSION}; then
+        echo "Deployment failed for version ${VERSION}"
+        exit 1
+      fi
+```
+
+## Migration Best Practices
+
+### 1. Gradual Adoption
+
+- **Start with AgileFlow** on new projects
+- **Gradually migrate** existing pipelines
+- **Test thoroughly** before full migration
+
+### 2. Team Training
+
+- **Train team members** on conventional commits
+- **Document workflow changes** clearly
+- **Provide examples** and templates
+
+### 3. Rollback Planning
+
+```yaml
+# ✅ Good - Rollback capability
+rollback:
+  stage: deploy
+  script:
+    - |
+      PREVIOUS_VERSION=$(git describe --abbrev=0 --tags v${VERSION%.*}.$((10#${VERSION##*.} - 1)))
+      kubectl set image deployment/myapp myapp=myapp:${PREVIOUS_VERSION}
+  when: manual
+  allow_failure: true
+```
+
+## Documentation Best Practices
+
+### 1. Keep Documentation Updated
+
+- **Update README** with new features
+- **Document breaking changes** clearly
+- **Provide examples** for common use cases
+
+### 2. Version-Specific Documentation
+
+```yaml
+# ✅ Good - Generate version-specific docs
+docs:
+  stage: deploy
+  script:
+    - |
+      echo "# Version ${VERSION}" > docs/versions/${VERSION}.md
+      echo "Released: $(date)" >> docs/versions/${VERSION}.md
+      echo "Changes: $(git tag -l -n99 ${VERSION})" >> docs/versions/${VERSION}.md
+```
+
+## Related Documentation
+
+- [Getting Started](./getting-started.md) - Quick start guide
+- [Conventional Commits](./conventional-commits.md) - Commit message format
+- [GitLab CI Template](./gitlab-ci-template.md) - Template configuration
+- [Configuration](./configuration.md) - Environment variables
+- [Troubleshooting](./troubleshooting.md) - Common issues and solutions