@logickernel/agileflow 0.4.0 → 0.4.2

package/docs/conventional-commits.md

@@ -1,234 +1,281 @@
 # Conventional Commits
 
-This document describes the conventional commit format used in AgileFlow and how it affects version bumping.
+AgileFlow uses [Conventional Commits](https://www.conventionalcommits.org/) to automatically determine version bumps and generate release notes.
 
-## Version Bump Logic
+## Commit Format
 
-AgileFlow automatically determines version bumps based on conventional commit messages using the following logic:
+```
+type(scope): description
+
+[optional body]
+
+[optional footer]
+```
+
+### Components
 
-### For versions 1.0.0 and above:
-- **Major version bump (X.0.0)**: Breaking changes (`!` suffix or `BREAKING CHANGE:` in footer)
-- **Minor version bump (0.X.0)**: New features (`feat:`)
-- **Patch version bump (0.0.X)**: Bug fixes, performance improvements, build system changes, CI changes, refactors, reverts, tests, or dependency updates
-- **No version bump**: Documentation, style changes, or chores (unless they affect build artifacts)
+| Part | Required | Description |
+|------|----------|-------------|
+| `type` | Yes | Type of change (feat, fix, etc.) |
+| `scope` | No | Area affected (auth, api, ui) |
+| `!` | No | Breaking change indicator |
+| `description` | Yes | Short summary |
+| `body` | No | Detailed explanation |
+| `footer` | No | Breaking changes, issue refs |
 
-### For pre-1.0.0 versions (0.x.x):
-- **Minor version bump (0.X.0)**: Breaking changes (`!` suffix or `BREAKING CHANGE:` in footer)
-- **Patch version bump (0.0.X)**: New features, bug fixes, performance improvements, build system changes, CI changes, refactors, reverts, tests, or dependency updates
-- **No version bump**: Documentation, style changes, or chores (unless they affect build artifacts)
+---
 
 ## Commit Types and Version Impact
 
-| Commit Type | Description | (>1.0.0) | (0.x.x) |
-|-------------|-------------|----------|---------|
-| [feat](./conventional-commits/type-feat.md) | New features | **Minor** | **Patch** |
-| [fix](./conventional-commits/type-fix.md) | Bug fixes | **Patch** | **Patch** |
-| [perf](./conventional-commits/type-perf.md) | Performance improvements | **Patch** | **Patch** |
-| [build](./conventional-commits/type-build.md) | Build system changes | **Patch** | **Patch** |
-| [ci](./conventional-commits/type-ci.md) | CI/CD changes | **Patch** | **Patch** |
-| [refactor](./conventional-commits/type-refactor.md) | Code refactoring | **Patch** | **Patch** |
-| [revert](./conventional-commits/type-revert.md) | Revert previous commits | **Patch** | **Patch** |
-| [test](./conventional-commits/type-test.md) | Test additions/changes | **Patch** | **Patch** |
-| [docs](./conventional-commits/type-docs.md) | Documentation changes | **None** | **None** |
-| [style](./conventional-commits/type-style.md) | Code style changes | **None** | **None** |
-| [chore](./conventional-commits/type-chore.md) | Maintenance tasks | **None** | **None** |
+| Type | Description | 1.0.0+ | 0.x.x |
+|------|-------------|--------|-------|
+| `feat` | New features | Minor | Patch |
+| `fix` | Bug fixes | Patch | Patch |
+| `perf` | Performance improvements | Patch | Patch |
+| `refactor` | Code refactoring | Patch | Patch |
+| `build` | Build system changes | Patch | Patch |
+| `ci` | CI/CD changes | Patch | Patch |
+| `test` | Test changes | Patch | Patch |
+| `revert` | Revert commits | Patch | Patch |
+| `docs` | Documentation | None | None |
+| `style` | Code style | None | None |
+| `chore` | Maintenance | None | None |
 
-### Dependency Updates
+### Breaking Changes
 
-Dependency updates are handled consistently based on their impact:
+Breaking changes trigger a major version bump (or minor for 0.x.x):
 
-- **`build(deps):`** - Always triggers patch version bump (affects build artifacts)
-- **`chore(deps):`** - Triggers patch version bump if it affects runtime dependencies, no bump for dev/test-only dependencies
+```bash
+# Using ! suffix
+feat!: remove deprecated API
 
-#### Examples:
-```
-build(deps): upgrade React to 18.2.0          # Patch bump (affects runtime)
-chore(deps): bump lodash to 4.17.21          # Patch bump (runtime dependency)
-chore(deps): bump jest to 29.0.0 [skip release]  # No bump (dev dependency)
+# Using footer
+feat: change response format
+
+BREAKING CHANGE: Response now uses camelCase
 ```
 
-## Breaking Changes
+---
 
-Breaking changes can be indicated in two ways:
+## Examples
+
+### Features
 
-1. **Exclamation mark suffix**: `feat!: breaking change` or `feat(scope)!: breaking change`
-2. **BREAKING CHANGE in footer**: Any commit with `BREAKING CHANGE:` in the commit footer/trailer section
+```bash
+feat: add user authentication
+feat(auth): implement OAuth2 login
+feat(api): add rate limiting endpoint
+```
 
-**Important**: Breaking change indicators in the commit body are not supported and may cause false positives. Always use the footer section.
+### Fixes
 
-### Breaking Change Examples:
+```bash
+fix: resolve null pointer exception
+fix(auth): handle expired tokens correctly
+fix(ui): correct button alignment on mobile
 ```
-feat!: remove deprecated API endpoints
 
-feat(auth)!: change authentication flow
+### Performance
 
-fix!: modify database schema
+```bash
+perf: optimize database queries
+perf(cache): implement Redis connection pooling
+```
+
+### Refactoring
 
-feat: new feature
-BREAKING CHANGE: The /api/v1/users endpoint has been removed
+```bash
+refactor: simplify authentication logic
+refactor(api): extract validation middleware
 ```
 
-## Commit Message Format
+### Breaking Changes
 
-The standard format for conventional commits is:
+```bash
+feat!: remove v1 API endpoints
+feat(auth)!: change token format to JWT
 
-```text
-type[!]?(scope)?: description
+fix: update database schema
 
-[optional body]
+BREAKING CHANGE: User table now requires email field
+```
+
+### Documentation
 
-[optional footer(s)]
+```bash
+docs: update installation guide
+docs(api): add authentication examples
+docs(readme): improve getting started section
 ```
 
-### Format Components:
-- **type**: The type of change (feat, fix, perf, etc.)
-- **!**: Optional breaking change indicator
-- **scope**: Optional scope in parentheses (e.g., auth, api, ui)
-- **description**: Short description of the change
-- **body**: Optional detailed explanation
-- **footer**: Optional footers like `BREAKING CHANGE:` or `[skip release]`
+### No Version Bump
 
-## Non-Conventional Commits
+```bash
+docs: update README
+style: format code with prettier
+chore: update development dependencies
+```
 
-Commits that don't follow the conventional format are handled as follows:
+---
+
+## Version Bump Priority
 
-- **Version bumping**: Non-conventional commits trigger **patch version bumps by default** unless they contain `[skip release]`
-- **Release notes**: They appear under "Other changes" section
-- **Examples**: `git merge`, `git revert`, or plain text commits
+When multiple commits exist, the highest priority wins:
 
-### Skip Release Convention
+1. **Breaking changes** → Major (or Minor for 0.x.x)
+2. **Features** → Minor (or Patch for 0.x.x)
+3. **Fixes, Performance, etc.** → Patch
+4. **Docs, Style, Chore** → No bump
 
-Use `[skip release]` suffix to explicitly prevent version bumping:
+### Example
 
+If commits since last version include:
 ```
-docs: update internal notes [skip release]
-chore: update local config [skip release]
-test: add debug logging [skip release]
+feat: add new dashboard
+fix: resolve login bug
+docs: update README
 ```
 
-## Release Note Generation
+Result: **Minor bump** (feat has highest priority)
 
-AgileFlow automatically generates organized release notes by grouping commits by type. The system follows this specific order:
+---
 
-1. **Features** - New functionality
-2. **Bug fixes** - Bug resolutions
-3. **Performance improvements** - Performance enhancements
-4. **Refactors** - Code refactoring
-5. **Documentation** - Documentation updates
-6. **Build system** - Build tooling changes
-7. **CI** - Continuous integration changes
-8. **Chores** - Maintenance tasks
-9. **Tests** - Test additions/changes (placed after chores as they're not user-facing)
-10. **Code style** - Formatting and style changes
-11. **Reverts** - Reverted changes
-12. **Other changes** - Non-conventional commits
+## Release Notes Generation
 
-### Breaking Change Indicators
-
-When breaking changes are detected, they are automatically prefixed with `BREAKING: ` in the release notes:
+AgileFlow groups commits by type for release notes:
 
 ```
-v2.0.0
+v1.2.4
 
-Features:
-- BREAKING: auth: change authentication flow
-- BREAKING: remove deprecated API endpoints
+### Features
+- add user dashboard
+- implement API rate limiting
 
-Bug fixes:
-- BREAKING: modify database schema
-```
+### Bug fixes
+- resolve login validation error
+- fix timeout on large uploads
 
-## Examples
+### Performance improvements
+- optimize database queries
 
-### Major Version Bump (1.0.0+)
+### Documentation
+- update API reference
 ```
-feat!: remove deprecated API endpoints
 
-feat(auth)!: change authentication flow
+### Breaking Changes in Notes
 
-fix!: modify database schema
-BREAKING CHANGE: Database schema has changed
-```
+Breaking changes are highlighted:
 
-### Minor Version Bump
 ```
-feat: add new user management dashboard
-feat(auth): implement two-factor authentication
-feat(api): add user search endpoint
+v2.0.0
+
+### Features
+- BREAKING: remove deprecated API endpoints
+- BREAKING: change authentication flow
 ```
 
-### Patch Version Bump
+---
+
+## Skip Release
+
+Use `[skip release]` to prevent version bump:
+
+```bash
+chore(deps): bump jest to 29.0.0 [skip release]
+docs: internal notes [skip release]
 ```
-fix: resolve user login issue
-fix(auth): correct null handling in user lookup
-perf: optimize database queries
-perf(cache): improve Redis connection pooling
-build: update webpack to v5
-build(deps): upgrade React to 18.2.0
-ci: add GitHub Actions workflow
-ci(gitlab): update pipeline configuration
-refactor: extract common utilities
-refactor(auth): simplify token validation
-revert: "feat: add user authentication"
-test: add unit tests for auth module
-test(integration): add API endpoint tests
-chore(deps): bump lodash to 4.17.21
+
+---
+
+## Non-Conventional Commits
+
+Commits not following the format:
+- Trigger **patch bump** by default
+- Appear under "Other changes" in release notes
+- Use `[skip release]` to prevent bump
+
+---
+
+## Best Practices
+
+### 1. Use Clear Types
+
+```bash
+# ✅ Correct type
+feat: add login feature
+fix: resolve crash on startup
+
+# ❌ Wrong type
+fix: add login feature  # Should be feat
+feat: fix crash         # Should be fix
 ```
 
-### No Version Bump
+### 2. Add Meaningful Scopes
+
+```bash
+# ✅ Helpful scope
+feat(auth): add OAuth2 support
+fix(api): handle timeout errors
+
+# ✅ Also fine without scope
+feat: add OAuth2 support
+fix: handle timeout errors
 ```
-docs: update API documentation
-docs(readme): add installation instructions
-style: format code with prettier
-style(eslint): enforce consistent formatting
-chore: update local configuration
-chore(deps): bump jest to 29.0.0 [skip release]
+
+### 3. Write Clear Descriptions
+
+```bash
+# ✅ Clear and specific
+feat(auth): add two-factor authentication via SMS
+fix(api): prevent timeout on uploads larger than 100MB
+
+# ❌ Vague
+feat: add 2fa
+fix: fix timeout
 ```
 
-## Version Bump Priority
+### 4. Mark Breaking Changes
 
-When multiple commit types are present in the commit history since the last version, the highest priority bump is applied:
+```bash
+# ✅ Properly marked
+feat!: remove deprecated endpoints
 
-1. **Breaking changes** → Major version bump (or minor for 0.x.x)
-2. **Features** → Minor version bump (or patch for 0.x.x)
-3. **Fixes, Performance, Build, CI, Refactor, Revert, Test, Dependencies** → Patch version bump
-4. **Documentation, Style, Chores** → No version bump (unless they affect build artifacts)
+# ❌ Breaking change not marked
+feat: remove deprecated endpoints
+```
 
-**Non-conventional commits** trigger patch version bumps by default unless they contain `[skip release]`.
+### 5. Use Present Tense
 
-This ensures semantic versioning follows the [SemVer specification](https://semver.org/).
+```bash
+# ✅ Present tense
+feat: add user authentication
 
-## Implementation Details
+# ❌ Past tense
+feat: added user authentication
+```
 
-AgileFlow's versioning system:
+---
 
-- **Analyzes commit messages** since the last version tag
-- **Groups changes by type** for organized release notes using the defined section order
-- **Generates comprehensive tag messages** with categorized changes
-- **Supports scoped commits** for better organization
-- **Handles breaking changes** automatically with `BREAKING: ` prefix
-- **Creates annotated tags** with detailed commit summaries
-- **Falls back to flat list** for repositories without conventional commits
-- **Supports metadata** in version tags (e.g., `v1.0.0-alpha.1`)
-- **Treats non-conventional commits** as patch-level changes by default
-- **Respects `[skip release]`** convention for explicit version control
+## Commit Type Details
 
-## Best Practices
+For detailed guidance on each type, see:
+
+- [feat](./conventional-commits/type-feat.md) — Features
+- [fix](./conventional-commits/type-fix.md) — Bug fixes
+- [perf](./conventional-commits/type-perf.md) — Performance
+- [refactor](./conventional-commits/type-refactor.md) — Refactoring
+- [build](./conventional-commits/type-build.md) — Build system
+- [ci](./conventional-commits/type-ci.md) — CI/CD
+- [test](./conventional-commits/type-test.md) — Tests
+- [docs](./conventional-commits/type-docs.md) — Documentation
+- [style](./conventional-commits/type-style.md) — Code style
+- [chore](./conventional-commits/type-chore.md) — Maintenance
+- [revert](./conventional-commits/type-revert.md) — Reverts
 
-1. **Use conventional commit types** consistently
-2. **Add scopes** when changes affect specific areas
-3. **Use breaking change indicators** (`!` or `BREAKING CHANGE:` in footer) for incompatible changes
-4. **Write clear descriptions** that explain what changed
-5. **Keep commits focused** on single changes
-6. **Use present tense** in commit messages ("add feature" not "added feature")
-7. **Follow the established section order** for consistent release notes
-8. **Use `[skip release]`** for dev/test dependencies that shouldn't trigger releases
-9. **Place breaking changes in footer** to avoid false positives
-10. **Group dependency updates** consistently: `build(deps)` for runtime, `chore(deps)` for maintenance
+---
 
 ## Related Documentation
 
-- [Getting Started](./getting-started.md) - Quick start guide
-- [Release Management](./release-management.md) - How versions are managed
-- [GitLab CI Template](./gitlab-ci-template.md) - CI/CD integration
-- [Branching Strategy](./branching-strategy.md) - Development workflow
+- [Getting Started](./getting-started.md) — Quick start
+- [Release Management](./release-management.md) — Version management
+- [Branching Strategy](./branching-strategy.md) — Git workflow