## Curation Note Consistent commit messages enable automated changelog generation, semantic versioning, and searchable project history. The Conventional Commits specification has become the industry standard, but applying it correctly requires understanding commit types, scopes, and when to use breaking change indicators. This skill from obra/superpowers codifies the patterns that maintainable open-source projects follow. ## Conventional Commit Format ``` <type>(<scope>): <description> [optional body] [optional footer(s)] ``` ### Types | Type | Description | Changelog Section | | ---------- | --------------------------- | ----------------- | | `feat` | New feature | Features | | `fix` | Bug fix | Bug Fixes | | `docs` | Documentation only | Documentation | | `style` | Formatting, no code change | (hidden) | | `refactor` | Code change, no feature/fix | (hidden) | | `perf` | Performance improvement | Performance | | `test` | Adding/updating tests | (hidden) | | `build` | Build system changes | (hidden) | | `ci` | CI configuration | (hidden) | | `chore` | Maintenance tasks | (hidden) | | `revert` | Reverting previous commit | Reverts | ### Scope Detection Analyze changed files to determine appropriate scope: ```bash src/auth/login.ts auth src/api/users.ts api components/Button.tsx ui lib/database/queries.ts db tests/integration/auth.test.ts auth ``` ### Examples **Simple Feature:** ``` feat(auth): add password reset functionality Users can now request a password reset email from the login page. The reset link expires after 24 hours. ``` **Bug Fix:** ``` fix(api): handle null response from external service The weather API occasionally returns null for forecast data. Added null check and fallback to cached data. Fixes #1234 ``` **Breaking Change:** ``` feat(api)!: change authentication to use JWT BREAKING CHANGE: API now requires JWT tokens instead of session cookies. All clients must be updated to use the new authentication flow. Migration guide: docs/migration/jwt-auth.md ``` **Documentation:** ``` docs(readme): update installation instructions Added section for Docker deployment. Fixed broken links to API documentation. ``` **Performance:** ``` perf(db): add index for user lookup queries Added composite index on (email, tenant_id). Improves login query from 120ms to 3ms. ``` ## Commit Message Guidelines ### Subject Line 1. **50 characters or less** - Fits in git log summary 2. **Imperative mood** - "Add feature" not "Added feature" 3. **No period at end** - It's a title, not a sentence 4. **Capitalize first letter** - After the type prefix ### Body 1. **72 characters per line** - Wraps nicely in terminals 2. **Explain what and why** - Not how (code shows how) 3. **Blank line after subject** - Required for git parsing 4. **Use bullet points** - For multiple items ### Footer 1. **Reference issues** - `Fixes #123`, `Closes #456` 2. **Breaking changes** - `BREAKING CHANGE: description` 3. **Co-authors** - `Co-authored-by: Name <email>` ## Analyzing Changes for Commits ### Workflow ```bash git diff --cached --stat git diff --cached --name-only | head -5 ``` ### Multi-File Changes When changes span multiple areas: ``` feat: implement user notification system - Add notification service with email and push support (api) - Create notification preferences UI component (ui) - Add database migrations for notification tables (db) This is a foundational change for the upcoming alerts feature. ``` ## Semantic Versioning Integration Commit types map to version bumps: | Commit Type | Version Bump | | ----------------- | ------------- | | `fix` | PATCH (0.0.x) | | `feat` | MINOR (0.x.0) | | `BREAKING CHANGE` | MAJOR (x.0.0) | Tools like `semantic-release` use this to automate versioning. ## Best Practices 1. **Atomic commits** - One logical change per commit 2. **Commit early, commit often** - Smaller commits are easier to review 3. **Never commit broken code** - Each commit should pass tests 4. **Use present tense** - "Add" not "Added" 5. **Reference issues** - Creates traceability 6. **Avoid generic messages** - "Fix bug" tells nothing 7. **Squash WIP commits** - Before merging to main ## Anti-Patterns ```bash git commit -m "fix" git commit -m "WIP" git commit -m "Updates" git commit -m "Review comments" git commit -m "Fixed the thing that was broken" git commit -m "fix(auth): prevent session fixation attack" git commit -m "feat(search): add fuzzy matching for product names" git commit -m "refactor(api): extract validation into middleware" ``` ## Related Resources - [Conventional Commits](https://www.conventionalcommits.org/) - [How to Write a Commit Message](https://cbea.ms/git-commit/) - [Semantic Versioning](https://semver.org/)