@logickernel/agileflow 0.1.0

package/docs/configuration.md

@@ -0,0 +1,232 @@
+# Configuration Guide
+
+AgileFlow uses environment variables for configuration, making it easy to customize behavior across different environments and deployment scenarios.
+
+## Environment Variables
+
+### Required Variables
+
+These environment variables must be set for AgileFlow to function properly:
+
+#### GitLab CI/CD Variables
+
+- **`GITLAB_USER_NAME`** - Username for git commits and tag creation
+  - **Example**: `AgileFlow Bot`
+  - **Purpose**: Sets the author name for version tags and commits
+  - **Required**: Yes
+
+- **`GITLAB_USER_EMAIL`** - Email address for git commits and tag creation
+  - **Example**: `agileflow@example.com`
+  - **Purpose**: Sets the author email for version tags and commits
+  - **Required**: Yes
+
+- **`CI_SERVER_HOST`** - GitLab server hostname
+  - **Example**: `gitlab.example.com`
+  - **Purpose**: Used for generating commit pipeline URLs and API calls
+  - **Required**: Yes
+
+- **`CI_PROJECT_PATH`** - GitLab project path (group/project)
+  - **Example**: `mygroup/myproject`
+  - **Purpose**: Used for API calls and URL generation
+  - **Required**: Yes
+
+- **`AGILEFLOW_TOKEN`** - GitLab access token with API permissions
+  - **Example**: `glpat-xxxxxxxxxxxxxxxxxxxx`
+  - **Purpose**: Authenticates API calls for tag creation and repository access
+  - **Required**: Yes
+  - **Scopes**: `api` access required
+  - **Role**: `maintainer` or higher recommended
+
+### Optional Variables
+
+These variables can be set to customize AgileFlow behavior:
+
+#### Version Generation
+
+- **`AGILEFLOW_MAX_COMMIT_LINES`** - Maximum number of commit lines in release notes
+  - **Default**: `50`
+  - **Example**: `100`
+  - **Purpose**: Controls the length of generated release notes
+
+- **`AGILEFLOW_INCLUDE_MERGE_COMMITS`** - Whether to include merge commits in release notes
+  - **Default**: `false`
+  - **Example**: `true`
+  - **Purpose**: Controls whether merge commits appear in release notes
+
+#### Git Configuration
+
+- **`GIT_COMMITTER_NAME`** - Override committer name (if different from author)
+  - **Default**: Uses `GITLAB_USER_NAME`
+  - **Example**: `CI Bot`
+  - **Purpose**: Sets the committer name for git operations
+
+- **`GIT_COMMITTER_EMAIL`** - Override committer email (if different from author)
+  - **Default**: Uses `GITLAB_USER_EMAIL`
+  - **Example**: `ci@example.com`
+  - **Purpose**: Sets the committer email for git operations
+
+## Configuration Examples
+
+### Basic GitLab CI Configuration
+
+```yaml
+# .gitlab-ci.yml
+variables:
+  GITLAB_USER_NAME: "AgileFlow Bot"
+  GITLAB_USER_EMAIL: "agileflow@example.com"
+  CI_SERVER_HOST: "gitlab.example.com"
+  CI_PROJECT_PATH: "mygroup/myproject"
+
+include:
+  - local: templates/AgileFlow.gitlab-ci.yml
+
+build:
+  stage: build
+  script:
+    - echo "Building version ${VERSION}"
+  needs:
+    - agileflow
+```
+
+### Advanced Configuration with Custom Options
+
+```yaml
+# .gitlab-ci.yml
+variables:
+  GITLAB_USER_NAME: "AgileFlow Bot"
+  GITLAB_USER_EMAIL: "agileflow@example.com"
+  CI_SERVER_HOST: "gitlab.example.com"
+  CI_PROJECT_PATH: "mygroup/myproject"
+  AGILEFLOW_MAX_COMMIT_LINES: "100"
+  AGILEFLOW_INCLUDE_MERGE_COMMITS: "false"
+
+include:
+  - local: templates/AgileFlow.gitlab-ci.yml
+
+build:
+  stage: build
+  script:
+    - echo "Building version ${VERSION}"
+  needs:
+    - agileflow
+```
+
+### Environment-Specific Configuration
+
+```yaml
+# .gitlab-ci.yml
+include:
+  - local: templates/AgileFlow.gitlab-ci.yml
+
+# Development environment
+build-dev:
+  stage: build
+  variables:
+    AGILEFLOW_MAX_COMMIT_LINES: "25"
+  script:
+    - echo "Building dev version ${VERSION}"
+  needs:
+    - agileflow
+
+# Production environment
+build-prod:
+  stage: build
+  variables:
+    AGILEFLOW_MAX_COMMIT_LINES: "100"
+  script:
+    - echo "Building production version ${VERSION}"
+  needs:
+    - agileflow
+```
+
+## Setting Variables in GitLab
+
+### Project-Level Variables
+
+1. Go to your GitLab project
+2. Navigate to **Settings > CI/CD**
+3. Expand **Variables**
+4. Add each required variable:
+   - **Key**: `GITLAB_USER_NAME`
+   - **Value**: `AgileFlow Bot`
+   - **Type**: Variable
+   - **Environment scope**: All (default)
+   - **Protect variable**: Yes (recommended)
+   - **Mask variable**: No
+
+### Group-Level Variables
+
+For organization-wide consistency:
+
+1. Go to your GitLab group
+2. Navigate to **Settings > CI/CD**
+3. Expand **Variables**
+4. Add common variables like `GITLAB_USER_NAME` and `GITLAB_USER_EMAIL`
+
+### Instance-Level Variables
+
+For self-managed GitLab instances:
+
+1. Go to **Admin Area > Settings > CI/CD**
+2. Expand **Variables**
+3. Add instance-wide defaults
+
+## Security Considerations
+
+### Token Security
+
+- **Protect variables**: Enable protection for sensitive variables like `AGILEFLOW_TOKEN`
+- **Mask variables**: Don't mask variables that need to be visible in logs
+- **Scope variables**: Limit variable scope to specific environments when possible
+- **Rotate tokens**: Regularly rotate access tokens
+
+### Access Control
+
+- **Minimal permissions**: Use tokens with minimal required permissions
+- **Role-based access**: Ensure tokens have appropriate role assignments
+- **Audit access**: Regularly review token access and usage
+
+## Troubleshooting Configuration
+
+### Common Configuration Issues
+
+**Missing Required Variables**
+```
+Error: Missing required environment variable: GITLAB_USER_NAME
+```
+**Solution**: Add the missing variable to your GitLab CI/CD variables.
+
+**Invalid Token Permissions**
+```
+Error: Permission denied. The AGILEFLOW_TOKEN needs "api" scope and maintainer role.
+```
+**Solution**: Update the token to have proper permissions and role.
+
+**Invalid Project Path**
+```
+Error: Invalid project path format
+```
+**Solution**: Ensure `CI_PROJECT_PATH` follows the format `group/project`.
+
+### Debug Configuration
+
+Add a debug job to verify configuration:
+
+```yaml
+debug-config:
+  stage: build
+  script:
+    - echo "GITLAB_USER_NAME: ${GITLAB_USER_NAME}"
+    - echo "CI_SERVER_HOST: ${CI_SERVER_HOST}"
+    - echo "CI_PROJECT_PATH: ${CI_PROJECT_PATH}"
+    - echo "AGILEFLOW_TOKEN: ${AGILEFLOW_TOKEN:0:10}..."
+  needs:
+    - agileflow
+```
+
+## Related Documentation
+
+- [Installation Guide](./installation.md) - Setup and configuration
+- [GitLab CI Template](./gitlab-ci-template.md) - Template configuration
+- [Troubleshooting](./troubleshooting.md) - Common issues and solutions
+- [CLI Reference](./cli-reference.md) - Command-line configuration

package/docs/conventional-commits/type-build.md

@@ -0,0 +1,23 @@
+# Build System (`build`)
+
+Changes that affect the build tooling or dependencies.
+
+**Use for**:
+- Dependency updates
+- Lockfile changes
+- Dockerfile modifications
+- Build script updates
+- Compiler configurations
+- Bundler settings
+
+**Avoid for**:
+- Runtime code changes
+- CI-only configuration
+
+**Examples**:
+```text
+build(deps): update React to version 18
+build(docker): optimize Docker image layers
+build(webpack): configure code splitting
+build(npm): update package-lock.json
+```

package/docs/conventional-commits/type-chore.md

@@ -0,0 +1,24 @@
+# Chores (`chore`)
+
+Routine tasks that do not affect source behavior or tests.
+
+**Use for**:
+- Repository housekeeping
+- License file updates
+- Issue template changes
+- File renames without behavior change
+- Git configuration
+- Development environment setup
+
+**Avoid for**:
+- Dependency changes
+- Build system modifications
+- Code formatting
+
+**Examples**:
+```text
+chore: update .gitignore patterns
+chore: add issue templates
+chore: reorganize project structure
+chore: update development setup instructions
+```

package/docs/conventional-commits/type-ci.md

@@ -0,0 +1,23 @@
+# CI/CD (`ci`)
+
+Changes to continuous integration configuration and automation. They usually do not affect source behavior, if they do, they must be marked as ! or add a BREAKING FIX footer.
+
+**Use for**:
+- Pipeline definitions
+- Job configurations
+- Cache settings
+- CI scripts
+- Deployment automation
+- Test configurations
+
+**Avoid for**:
+- Build tooling that affects local builds
+- Application code changes
+
+**Examples**:
+```text
+ci(gitlab): add deployment job for staging
+ci(docker): configure multi-stage builds
+ci(tests): add integration test suite
+ci(deploy): automate production deployments
+```

package/docs/conventional-commits/type-docs.md

@@ -0,0 +1,23 @@
+# Documentation (`docs`)
+
+Documentation-only changes.
+
+**Use for**:
+- README updates
+- API documentation
+- Code examples
+- Architecture decision records (ADRs)
+- Inline code comments
+- User guides
+
+**Avoid for**:
+- Code changes that affect behavior
+- Configuration changes
+
+**Examples**:
+```text
+docs: update installation instructions
+docs(api): add endpoint documentation
+docs: add troubleshooting guide
+docs: update contributing guidelines
+```

package/docs/conventional-commits/type-feat.md

@@ -0,0 +1,28 @@
+# Features (`feat`)
+
+Introduces new user- or API-facing capabilities without removing existing behavior.
+
+## Examples
+
+```text
+feat(api) add user authentication endpoint
+feat(cli): implement --dry-run flag for deployments
+feat(ui): add dark mode toggle
+feat(auth): support OAuth2 login flow
+```
+
+## Use for
+
+- New endpoints or API methods
+- CLI commands and options
+- Configuration options
+- UI components and features
+- Additive database migrations
+- New functionality
+
+## Avoid for
+
+- Internal-only refactors
+- Performance tweaks that don't add capability
+- Bug fixes
+

package/docs/conventional-commits/type-fix.md

@@ -0,0 +1,27 @@
+# Bug Fixes (`fix`)
+
+Corrects faulty behavior, regressions, crashes, data corruption, or incorrect outputs.
+
+## Examples
+
+```text
+fix(auth): handle empty refresh token gracefully
+fix(api): correct null pointer exception in user lookup
+fix(ui): resolve button click event not firing
+fix(db): fix transaction rollback on connection failure
+```
+
+## Use for
+
+- Logic errors and bugs
+- Off-by-one fixes
+- Null handling improvements
+- Race condition fixes
+- Flaky behavior resolution
+- Data validation fixes
+
+## Avoid for
+
+- Refactors that don't change behavior
+- Performance improvements
+- New features

package/docs/conventional-commits/type-perf.md

@@ -0,0 +1,24 @@
+# Performance (`perf`)
+
+Makes the system faster or leaner without changing public behavior or semantics.
+
+**Use for**:
+- Algorithmic improvements
+- Caching implementations
+- Reduced memory allocations
+- Optimized database queries
+- I/O batching
+- Performance optimizations
+
+**Avoid for**:
+- Feature additions
+- Bug fixes
+- Refactoring
+
+**Examples**:
+```text
+perf(cache): implement Redis caching for user sessions
+perf(db): optimize user query with proper indexing
+perf(api): batch database writes to reduce latency
+perf(ui): lazy load images for better page performance
+```

package/docs/conventional-commits/type-refactor.md

@@ -0,0 +1,24 @@
+# Refactors (`refactor`)
+
+Internal code changes that do not alter external behavior; improves structure, readability, or maintainability.
+
+**Use for**:
+- Code reorganization
+- Function extraction
+- Module restructuring
+- Technical debt reduction
+- Code cleanup
+- Renaming variables/functions
+
+**Avoid for**:
+- Behavior changes
+- New features
+- Bug fixes
+
+**Examples**:
+```text
+refactor(auth): extract authentication logic into service
+refactor(api): split monolithic controller into modules
+refactor(ui): reorganize component hierarchy
+refactor(db): normalize database schema
+```

package/docs/conventional-commits/type-revert.md

@@ -0,0 +1,16 @@
+# Reverts (`revert`)
+
+Reverts a previous commit.
+
+## Examples
+
+```text
+revert: feat(api): add user authentication endpoint
+revert: fix(auth): handle empty refresh token gracefully
+```
+
+## Use for
+
+- Explicit rollbacks
+- Undoing problematic changes
+- Reverting breaking changes

package/docs/conventional-commits/type-style.md

@@ -0,0 +1,24 @@
+# Code Style (`style`)
+
+Non-functional changes that do not affect the meaning of code.
+
+**Use for**:
+- Code formatting
+- Whitespace changes
+- Linter fixes
+- Import reordering
+- Code style compliance
+- Prettier/ESLint fixes
+
+**Avoid for**:
+- Refactoring
+- Behavior changes
+- Bug fixes
+
+**Examples**:
+```text
+style: apply Prettier formatting
+style: fix ESLint warnings
+style: reorder imports alphabetically
+style: fix trailing whitespace
+```

package/docs/conventional-commits/type-test.md

@@ -0,0 +1,24 @@
+# Tests (`test`)
+
+Adds or updates tests without changing runtime behavior.
+
+**Use for**:
+- New unit tests
+- Integration test additions
+- Test fixture updates
+- Test refactoring
+- Test coverage improvements
+- End-to-end test additions
+
+**Avoid for**:
+- Bug fixes
+- Feature additions
+- Behavior changes
+
+**Examples**:
+```text
+test(api): add unit tests for user service
+test(ui): add integration tests for login flow
+test(db): add database migration tests
+test(auth): add OAuth2 flow tests
+```