Conventional commits provide a consistent way to structure commit messages, which helps with automation, release notes generation, and understanding the history of a project. The format adheres to the following structure:
<type>(<scope>): <message>
Or, if the commit introduces a breaking change:
<type>(<scope>)!: <message>
For more details, see the official documentation: https://www.conventionalcommits.org
feat(api): add user registration endpoint
fix(auth): handle expired token edge case
refactor(core)!: remove deprecated session manager
BREAKING CHANGE: Session manager has been removed. Replace it with the new auth lifecycle.
Some teams like to use emojis as part of the commit message to make it easier to visually distinguish commit types. Emojis can be used in the message, but the commit type still follows the standard (e.g., fix:, feat:). Here's how it can be applied:
feat(auth): ✨ implement OAuth2 login
fix(ui): 🐛 resolve flickering issue in dark mode
refactor(core)!: ♻️ simplify session logic
BREAKING CHANGE: Session handling is now stateless and requires new configuration.
A new feature has been added.
Example:
feat(auth): add user login functionality
With Emoji:
feat(auth): ✨ add user login functionality
A bug has been fixed.
Example:
fix(ui): correct button alignment on mobile
With Emoji:
fix(ui): 🐛 correct button alignment on mobile
Changes related to documentation only.
Example:
docs: update README with new setup instructions
With Emoji:
docs: 📚 update README with new setup instructions
Changes that do not affect the meaning of the code (e.g., formatting, missing semicolons).
Example:
style(ui): update button padding and font size
With Emoji:
style(ui): 💅 update button padding and font size
Refactoring code (i.e., no new features, no bug fixes, but changes to the structure of the code).
Example:
refactor(auth): restructure authentication middleware
With Emoji:
refactor(auth): ♻️ restructure authentication middleware
Changes that improve performance.
Example:
perf(api): optimize database query for user search
With Emoji:
perf(api): ⚡ optimize database query for user search
Adding or updating tests.
Example:
test(auth): add unit tests for login functionality
With Emoji:
test(auth): 🧪 add unit tests for login functionality
Other changes that don't modify application behavior (e.g., build, tooling).
Example:
chore: update dependencies
With Emoji:
chore: 🔧 update dependencies
Changes that affect the build system or external dependencies (e.g., packaging, deployment).
Example:
build: configure webpack for production
With Emoji:
build: 🛠️ configure webpack for production
Changes related to continuous integration.
Example:
ci: add CircleCI configuration for automated testing
With Emoji:
ci: 🎡 add CircleCI configuration for automated testing
If your commit introduces a breaking change, use a ! immediately after the type or scope, and optionally include a BREAKING CHANGE: footer to explain it.
Example:
feat(auth)!: change token format to JWT v2
BREAKING CHANGE: Token format is now incompatible with previous versions. Clients must update to handle the new format.
This makes it easy for tools like semantic-release to detect breaking changes and bump major versions automatically.
By using Conventional Commits, you ensure a clean, organized commit history that can be easily understood by other developers and enable automation like changelog generation and semantic versioning.
Learn more at: https://www.conventionalcommits.org