# Commit Conventions > Git commit message guidelines ## 📋 Overview We follow [Conventional Commits](https://www.conventionalcommits.org/) specification for clear, semantic commit messages that support automated changelog generation and version management. ## 📝 Commit Message Format ``` (): [optional body] [optional footer(s)] ``` ### Components **Type**: The kind of change **Scope**: The area of the codebase affected (optional) **Subject**: Short description (imperative mood) **Body**: Detailed explanation (optional) **Footer**: Breaking changes, issue references (optional) ## 🏷️ Types ### Primary Types | Type | Description | Semantic Version | |------|-------------|------------------| | **feat** | New feature | Minor (0.X.0) | | **fix** | Bug fix | Patch (0.0.X) | | **docs** | Documentation only | - | | **style** | Code style (formatting, whitespace) | - | | **refactor** | Code change (not feat/fix) | - | | **perf** | Performance improvement | Patch (0.0.X) | | **test** | Add/update tests | - | | **chore** | Maintenance (deps, config) | - | | **build** | Build system/tools | - | | **ci** | CI configuration | - | | **revert** | Revert previous commit | - | ### Type Selection Guide ```bash # Adding new functionality feat: add project filtering # Fixing a bug fix: resolve session timeout issue # Improving performance perf: optimize database queries # Refactoring without behavior change refactor: simplify auth logic # Documentation docs: update API reference # Tests test: add project creation tests # Dependencies, configs chore: update dependencies ``` ## 🎯 Scopes Scopes indicate which part of the codebase is affected: ### Common Scopes ```bash # Applications web # Web frontend api # API server # Packages database # @izri/database trpc # @izri/trpc auth # @izri/auth shared # @izri/shared # Features projects # Project management tests # Test execution analysis # Repository analysis org # Organizations # Infrastructure docker # Docker configuration ci # CI/CD deps # Dependencies ``` ### Examples with Scopes ```bash feat(projects): add project filtering fix(auth): resolve session timeout docs(api): update tRPC documentation refactor(database): optimize query performance test(web): add component tests chore(deps): update to React 19 ``` ## ✍️ Subject Guidelines ### Rules 1. **Use imperative mood**: "add feature" not "added feature" 2. **No capitalization**: Start with lowercase 3. **No period**: Don't end with `.` 4. **Max 72 characters**: Keep it concise 5. **Be descriptive**: But not verbose ### Good Examples ```bash ✅ feat: add project filtering ✅ fix: resolve database connection timeout ✅ refactor: simplify project query logic ✅ docs: update installation instructions ``` ### Bad Examples ```bash ❌ Added new feature # Past tense ❌ Fix bug # Too vague ❌ feat: Added Project Filter # Capitalized ❌ fix: resolve the issue where the database connection was timing out frequently # Too long ``` ## 📖 Body Use the body to explain: - **What** changed - **Why** it changed - **How** it affects behavior ### Format - Wrap at 72 characters - Separate from subject with blank line - Use bullet points for multiple points ### Example ``` feat(projects): add advanced filtering Add support for filtering projects by: - Language (TypeScript, Python, Go) - Framework (React, Vue, FastAPI) - Date range This improves user experience when managing many projects and enables better organization. ``` ## 🔗 Footer Use footer for: - **Breaking changes**: `BREAKING CHANGE:` description - **Issue references**: `Closes #123`, `Fixes #456` - **Other metadata**: `Reviewed-by:`, `Refs:` ### Breaking Changes ``` feat(database)!: change project schema Rename 'repo' field to 'repository' for consistency. BREAKING CHANGE: Projects table 'repo' field renamed to 'repository'. Update all queries to use new field name. ``` ### Issue References ``` fix(auth): resolve session timeout Fixes #123 Closes #456 ``` ## 📋 Complete Examples ### Feature Addition ``` feat(tests): add test execution API Implement tRPC endpoint for running tests: - Support unit, integration, and E2E tests - Queue tests for async execution - Store results in database Closes #234 ``` ### Bug Fix ``` fix(api): prevent duplicate project creation Add unique constraint check before inserting new project. Returns existing project if repository URL already exists for user. Fixes #456 ``` ### Breaking Change ``` feat(auth)!: migrate to Better Auth Replace custom auth with Better Auth library for improved security and OAuth support. BREAKING CHANGE: - Session structure changed - Old sessions invalidated - Users must re-authenticate - Update auth middleware imports Closes #789 ``` ### Documentation ``` docs(contributing): add code style guide Add comprehensive code style documentation: - TypeScript conventions - React patterns - Testing guidelines - File organization ``` ### Refactoring ``` refactor(projects): simplify query logic Extract common query patterns into reusable functions. No behavior changes. ``` ### Multiple Changes ``` feat(web): improve project dashboard - Add real-time updates via WebSocket - Implement project sorting and filtering - Add pagination for large project lists - Improve loading states Closes #123, #124, #125 ``` ## 🔄 Reverting Commits ``` revert: feat(tests): add test execution API Revert commit abc1234 due to performance issues. This reverts commit abc1234567890. ``` ## 🛠️ Tools & Automation ### Commitlint Check commit messages automatically: ```bash # Install pnpm add -D @commitlint/cli @commitlint/config-conventional # Configure echo "module.exports = { extends: ['@commitlint/config-conventional'] }" > commitlint.config.js # Use in git hook npx commitlint --edit $1 ``` ### Commitizen Interactive commit message builder: ```bash # Install pnpm add -D commitizen cz-conventional-changelog # Use pnpm cz # or git cz ``` ### Husky + Commitlint Enforce commit conventions: ```bash # Install husky pnpm add -D husky # Set up npx husky install # Add commit-msg hook npx husky add .husky/commit-msg 'npx --no -- commitlint --edit $1' ``` ## ✅ Commit Checklist Before committing: - [ ] Message follows conventional format - [ ] Type is appropriate - [ ] Scope is accurate (if used) - [ ] Subject is descriptive and concise - [ ] Imperative mood used - [ ] No capitalization or period in subject - [ ] Body explains context (if needed) - [ ] Breaking changes documented - [ ] Issues referenced ## 🎯 Tips ### Atomic Commits Make commits focused and atomic: ```bash # ✅ Good: Separate commits git commit -m "feat(projects): add filtering UI" git commit -m "feat(projects): add filtering API" git commit -m "test(projects): add filtering tests" # ❌ Bad: Everything in one commit git commit -m "feat(projects): add filtering feature with UI, API, and tests" ``` ### Commit Frequency ```bash # ✅ Commit logical units of work # Each commit should be a complete, working change # ❌ Don't commit half-finished work # Unless using WIP commits (not for main branch) ``` ### WIP Commits For work-in-progress (on feature branches only): ```bash git commit -m "wip: implementing project filtering" # Squash before merging to main git rebase -i main ``` ## 📊 Changelog Generation Commits following this convention enable automated changelog generation: ```bash # Generate changelog npx conventional-changelog -p angular -i CHANGELOG.md -s # Release with automatic version bump npx standard-version ``` ### Changelog Output ```markdown ## [1.2.0](2024-01-15) ### Features * **projects**: add advanced filtering (#234) * **tests**: add test execution API (#456) ### Bug Fixes * **auth**: resolve session timeout (#789) * **api**: prevent duplicate project creation ### BREAKING CHANGES * **auth**: Users must re-authenticate after upgrade ``` ## 🔗 Related Documentation - **Code Style**: [Code style guide](./code-style.md) - **Pull Requests**: [PR process](./pull-requests.md) - **Testing**: [Testing guidelines](./testing-guidelines.md) --- *Next: [Pull Request Process](./pull-requests.md) →*