Git Conventional Commits Guide
This skill provides guidelines for writing clean, structured, and standardized commit messages and branch names using the Conventional Commits specification.
Branch Naming Conventions
Always use descriptive and structured branch names. This helps in understanding the context of the work.
Format
<type>/<issue-ticket>-<short-description>
Types
feature/orfeat/: For new featuresbugfix/orfix/: For bug fixeshotfix/: For critical production fixeschore/: For maintenance, dependency updates, etc.docs/: For documentation changes
Examples
feature/PROJ-123-add-user-loginfix/PROJ-456-resolve-null-pointerchore/update-dependencies
Conventional Commits Specification
Commit messages should be structured as follows:
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
Commit Types
| Type | Description |
|---|---|
feat |
A new feature |
fix |
A bug fix |
docs |
Documentation only changes |
style |
Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc) |
refactor |
A code change that neither fixes a bug nor adds a feature |
perf |
A code change that improves performance |
test |
Adding missing tests or correcting existing tests |
build |
Changes that affect the build system or external dependencies |
ci |
Changes to our CI configuration files and scripts |
chore |
Other changes that don't modify src or test files |
revert |
Reverts a previous commit |
Scope (Optional)
The scope provides context to where the changes were made (e.g., auth, ui, database).
Example: feat(auth): implement JWT token verification
Description
- Use the imperative, present tense: "change" not "changed" nor "changes".
- Don't capitalize the first letter.
- No dot (.) at the end.
Body (Optional)
- Just as in the description, use the imperative, present tense.
- The body should include the motivation for the change and contrast this with previous behavior.
Breaking Changes
A commit that has a footer BREAKING CHANGE:, or appends a ! after the type/scope, introduces a breaking API change.
Example:
feat(api)!: remove deprecated v1 endpoints
BREAKING CHANGE: The v1 endpoints are no longer available. Use v2 instead.
Checklist for Good Commits
- Have I used the correct type?
- Is the description concise and clear?
- Did I use the imperative mood in the subject line?
- Have I included a body to explain the 'why' if necessary?
- Are breaking changes clearly marked?