CleanArchitecture-template/.brain/.agent/skills/engineering-advanced-skills/release-manager/references/conventional-commits-guide.md

# Conventional Commits Guide

## Overview

Conventional Commits is a specification for adding human and machine readable meaning to commit messages. The specification provides an easy set of rules for creating an explicit commit history, which makes it easier to write automated tools for version management, changelog generation, and release planning.

## Basic Format

```
<type>[optional scope]: <description>

[optional body]

[optional footer(s)]
```

## Commit Types

### Primary Types

- **feat**: A new feature for the user (correlates with MINOR in semantic versioning)
- **fix**: A bug fix for the user (correlates with PATCH in semantic versioning)

### Secondary Types

- **build**: Changes that affect the build system or external dependencies (webpack, npm, etc.)
- **ci**: Changes to CI configuration files and scripts (Travis, Circle, BrowserStack, SauceLabs)
- **docs**: Documentation only changes
- **perf**: A code change that improves performance
- **refactor**: A code change that neither fixes a bug nor adds a feature
- **style**: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc.)
- **test**: Adding missing tests or correcting existing tests
- **chore**: Other changes that don't modify src or test files
- **revert**: Reverts a previous commit

### Breaking Changes

Any commit can introduce a breaking change by:
1. Adding `!` after the type: `feat!: remove deprecated API`
2. Including `BREAKING CHANGE:` in the footer

## Scopes

Scopes provide additional contextual information about the change. They should be noun describing a section of the codebase:

- `auth` - Authentication and authorization
- `api` - API changes
- `ui` - User interface
- `db` - Database related changes
- `config` - Configuration changes
- `deps` - Dependency updates

## Examples

### Simple Feature
```
feat(auth): add OAuth2 integration

Integrate OAuth2 authentication with Google and GitHub providers.
Users can now log in using their existing social media accounts.
```

### Bug Fix
```
fix(api): resolve race condition in user creation

When multiple requests tried to create users with the same email
simultaneously, duplicate records were sometimes created. Added
proper database constraints and error handling.

Fixes #234
```

### Breaking Change with !
```
feat(api)!: remove deprecated /v1/users endpoint

The deprecated /v1/users endpoint has been removed. All clients
should migrate to /v2/users which provides better performance
and additional features.

BREAKING CHANGE: /v1/users endpoint removed, use /v2/users instead
```

### Breaking Change with Footer
```
feat(auth): implement new authentication flow

Add support for multi-factor authentication and improved session
management. This change requires all users to re-authenticate.

BREAKING CHANGE: Authentication tokens issued before this release
are no longer valid. Users must log in again.
```

### Performance Improvement
```
perf(image): optimize image compression algorithm

Replaced PNG compression with WebP format, reducing image sizes
by 40% on average while maintaining visual quality.

Closes #456
```

### Dependency Update
```
build(deps): upgrade React to version 18.2.0

Updates React and related packages to latest stable versions.
Includes performance improvements and new concurrent features.
```

### Documentation
```
docs(readme): add deployment instructions

Added comprehensive deployment guide including Docker setup,
environment variables configuration, and troubleshooting tips.
```

### Revert
```
revert: feat(payment): add cryptocurrency support

This reverts commit 667ecc1654a317a13331b17617d973392f415f02.

Reverting due to security concerns identified in code review.
The feature will be re-implemented with proper security measures.
```

## Multi-paragraph Body

For complex changes, use multiple paragraphs in the body:

```
feat(search): implement advanced search functionality

Add support for complex search queries including:
- Boolean operators (AND, OR, NOT)
- Field-specific searches (title:, author:, date:)
- Fuzzy matching with configurable threshold
- Search result highlighting

The search index has been restructured to support these new
features while maintaining backward compatibility with existing
simple search queries.

Performance testing shows less than 10ms impact on search
response times even with complex queries.

Closes #789, #823, #901
```

## Footers

### Issue References
```
Fixes #123
Closes #234, #345
Resolves #456
```

### Breaking Changes
```
BREAKING CHANGE: The `authenticate` function now requires a second
parameter for the authentication method. Update all calls from
`authenticate(token)` to `authenticate(token, 'bearer')`.
```

### Co-authors
```
Co-authored-by: Jane Doe <jane@example.com>
Co-authored-by: John Smith <john@example.com>
```

### Reviewed By
```
Reviewed-by: Senior Developer <senior@example.com>
Acked-by: Tech Lead <lead@example.com>
```

## Automation Benefits

Using conventional commits enables:

### Automatic Version Bumping
- `fix` commits trigger PATCH version bump (1.0.0 → 1.0.1)
- `feat` commits trigger MINOR version bump (1.0.0 → 1.1.0)  
- `BREAKING CHANGE` triggers MAJOR version bump (1.0.0 → 2.0.0)

### Changelog Generation
```markdown
## [1.2.0] - 2024-01-15

### Added
- OAuth2 integration (auth)
- Advanced search functionality (search)

### Fixed
- Race condition in user creation (api)
- Memory leak in image processing (image)

### Breaking Changes
- Authentication tokens issued before this release are no longer valid
```

### Release Notes
Generate user-friendly release notes automatically from commit history, filtering out internal changes and highlighting user-facing improvements.

## Best Practices

### Writing Good Descriptions
- Use imperative mood: "add feature" not "added feature"
- Start with lowercase letter
- No period at the end
- Limit to 50 characters when possible
- Be specific and descriptive

### Good Examples
```
feat(auth): add password reset functionality
fix(ui): resolve mobile navigation menu overflow
perf(db): optimize user query with proper indexing
```

### Bad Examples
```
feat: stuff
fix: bug
update: changes
```

### Body Guidelines
- Separate subject from body with blank line
- Wrap body at 72 characters
- Use body to explain what and why, not how
- Reference issues and PRs when relevant

### Scope Guidelines
- Use consistent scope naming across the team
- Keep scopes short and meaningful
- Document your team's scope conventions
- Consider using scopes that match your codebase structure

## Tools and Integration

### Git Hooks
Use tools like `commitizen` or `husky` to enforce conventional commit format:

```bash
# Install commitizen
npm install -g commitizen cz-conventional-changelog

# Configure
echo '{ "path": "cz-conventional-changelog" }' > ~/.czrc

# Use
git cz
```

### Automated Validation
Add commit message validation to prevent non-conventional commits:

```javascript
// commitlint.config.js
module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [
      2, 'always',
      ['feat', 'fix', 'docs', 'style', 'refactor', 'perf', 'test', 'build', 'ci', 'chore', 'revert']
    ],
    'subject-case': [2, 'always', 'lower-case'],
    'subject-max-length': [2, 'always', 50]
  }
};
```

### CI/CD Integration
Integrate with release automation tools:
- **semantic-release**: Automated version management and package publishing
- **standard-version**: Generate changelog and tag releases
- **release-please**: Google's release automation tool

## Common Mistakes

### Mixing Multiple Changes
```
# Bad: Multiple unrelated changes
feat: add login page and fix CSS bug and update dependencies

# Good: Separate commits
feat(auth): add login page
fix(ui): resolve CSS styling issue  
build(deps): update React to version 18
```

### Vague Descriptions
```
# Bad: Not descriptive
fix: bug in code
feat: new stuff

# Good: Specific and clear
fix(api): resolve null pointer exception in user validation
feat(search): implement fuzzy matching algorithm
```

### Missing Breaking Change Indicators
```
# Bad: Breaking change not marked
feat(api): update user authentication

# Good: Properly marked breaking change
feat(api)!: update user authentication

BREAKING CHANGE: All API clients must now include authentication
headers in every request. Anonymous access is no longer supported.
```

## Team Guidelines

### Establishing Conventions
1. **Define scope vocabulary**: Create a list of approved scopes for your project
2. **Document examples**: Provide team-specific examples of good commits
3. **Set up tooling**: Use linters and hooks to enforce standards
4. **Review process**: Include commit message quality in code reviews
5. **Training**: Ensure all team members understand the format

### Scope Examples by Project Type
**Web Application:**
- `auth`, `ui`, `api`, `db`, `config`, `deploy`

**Library/SDK:**
- `core`, `utils`, `docs`, `examples`, `tests`

**Mobile App:**
- `ios`, `android`, `shared`, `ui`, `network`, `storage`

By following conventional commits consistently, your team will have a clear, searchable commit history that enables powerful automation and improves the overall development workflow.