conventional-commits

# Conventional Commits Format all commit messages according to the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification. This enables automated changelog generation, semantic versioning, and better commit history. ## Format Structure ``` <type>[optional scope]: <description> [optional body] [optional footer(s)] ``` ## Commit Types ### Required Types - **`feat:`** - A new feature (correlates with MINOR in Semantic Versioning) - **`fix:`** - A bug fix (correlates with PATCH in Semantic Versioning) ### Common Additional Types - **`docs:`** - Documentation only changes - **`style:`** - Code style changes (formatting, missing semicolons, etc.) - **`refactor:`** - Code refactoring without bug fixes or new features - **`perf:`** - Performance improvements - **`test:`** - Adding or updating tests - **`build:`** - Build system or external dependencies changes - **`ci:`** - CI/CD configuration changes - **`chore:`** - Other changes that don't modify src or test files - **`revert:`** - Reverts a previous commit ## Scope An optional scope provides additional contextual information about the section of the codebase: ``` feat(parser): add ability to parse arrays fix(auth): resolve token expiration issue docs(readme): update installation instructions ``` ## Description - Must immediately follow the colon and space after the type/scope - Use imperative mood ("add feature" not "added feature" or "adds feature") - Don't capitalize the first letter - No period at the end - Keep it concise (typically 50-72 characters) ## Body - Optional longer description providing additional context - Must begin one blank line after the description - Can consist of multiple paragraphs - Explain the "what" and "why" of the change, not the "how" ## Breaking Changes Breaking changes can be indicated in two ways: ### 1. Using `!` in the type/scope ``` feat!: send an email to the customer when a product is shipped feat(api)!: send an email to the customer when a product is shipped ``` ### 2. Using BREAKING CHANGE footer ``` feat: allow provided config object to extend other configs BREAKING CHANGE: `extends` key in config file is now used for extending other config files ``` ### 3. Both methods ``` chore!: drop support for Node 6 BREAKING CHANGE: use JavaScript features not available in Node 6. ``` ## Examples ### Simple feature ``` feat: add user authentication ``` ### Feature with scope ``` feat(auth): add OAuth2 support ``` ### Bug fix with body ``` fix: prevent racing of requests Introduce a request id and a reference to latest request. Dismiss incoming responses other than from latest request. Remove timeouts which were used to mitigate the racing issue but are obsolete now. ``` ### Breaking change ``` feat!: migrate to new API client BREAKING CHANGE: The API client interface has changed. All methods now return Promises instead of using callbacks. ``` ### Documentation update ``` docs: correct spelling of CHANGELOG ``` ### Multi-paragraph body with footers ``` fix: prevent racing of requests Introduce a request id and a reference to latest request. Dismiss incoming responses other than from latest request. Remove timeouts which were used to mitigate the racing issue but are obsolete now. Reviewed-by: Z Refs: #123 ``` ## Guidelines 1. **Always use a type** - Every commit must start with a type followed by a colon and space 2. **Use imperative mood** - Write as if completing the sentence "If applied, this commit will..." 3. **Be specific** - The description should clearly communicate what changed 4. **Keep it focused** - One logical change per commit 5. **Use scopes when helpful** - Scopes help categorize changes within a codebase 6. **Document breaking changes** - Always indicate breaking changes clearly ## Semantic Versioning Correlation - **`fix:`** → PATCH version bump (1.0.0 → 1.0.1) - **`feat:`** → MINOR version bump (1.0.0 → 1.1.0) - **BREAKING CHANGE** → MAJOR version bump (1.0.0 → 2.0.0) ## When to Use Use this format for: - All git commits - Commit message generation - Pull request merge commits - When the user asks about commit messages or git commits ## Common Mistakes to Avoid ❌ `Added new feature` (past tense, capitalized) ✅ `feat: add new feature` (imperative, lowercase) ❌ `fix: bug` (too vague) ✅ `fix: resolve null pointer exception in user service` ❌ `feat: add feature` (redundant) ✅ `feat: add user profile page` ❌ `feat: Added OAuth support.` (past tense, period) ✅ `feat: add OAuth support`