Conventional Commits Guideline

What Are Conventional Commits?

Conventional Commits is a standardized way of writing commit messages that adds human- and machine-readable meaning to your Git history.
It makes it easier to understand what changed and why, and enables automation for changelogs, versioning, and releases.

Why Use Conventional Commits?

Improves clarity and consistency of commit messages.
Makes code review and change tracking easier.
Enables automated changelogs and semantic versioning.
Helps categorize commits for better project insights.

Commit Message Format

<type>(optional scope): <description>

[optional body]

[footer(s)]

Commit Types

Type	Description

Type	Description
feat	A new feature
fix	A bug fix
refactor	Code change that neither fixes a bug nor adds a feature
docs	Documentation only changes
style	Changes that don’t affect code meaning (formatting, spacing, etc.)
test	Adding or updating tests
ci	CI configuration or pipeline changes
chore	Maintenance tasks, build process updates, or dependency changes

Commit Scope (optional)

Use scope to specify the affected module, feature, or area of code, e.g.:

feat(auth): add OAuth2 login

Keep scopes short and consistent.

Commit Description

Use imperative mood, e.g. add, fix, update (not “added”, “fixed”).
Keep it under ~72 characters.
Summarize what and why, not how.

Body (optional)

Use the body to explain details, motivation, or side effects.
Write in the present tense. Use bullet points for clarity.

Footer

Use for issue references:

Closes: #123
Related: #321

Examples

Feature

feat(user-profile): add profile picture upload

Add ability for users to upload a profile picture from the account page.

- Add upload button to profile page
- Implement API endpoint for uploads
- Add image validation (size and format)

Closes: #1234

Feature with Breaking Change

feat(payment): integrate new payment gateway

- Add new payment gateway integration
- Remove support for legacy gateway
- Update transaction handling

BREAKING CHANGE: removes support for the old gateway. Merchants must update configurations.

Closes: #1234

Bug Fix

fix(auth): handle password reset errors gracefully

Handle invalid email input during password reset without crashing.
Show user-friendly error messages on failure.

Closes: #1234

Documentation

docs(readme): add dependency installation instructions

- List required dependencies with versions
- Add setup steps for local development

Closes: #1234

Best Practices

✅ Use imperative mood: “fix bug,” not “fixed bug”
✅ Keep messages short and meaningful
✅ Limit scope to a single logical change
✅ Add context in the body if needed
✅ Reference issues or PRs in the footer
✅ Maintain consistent structure and tone

Tools

For IntelliJ IDEA users:

Commitlint Conventional Commit plugin
Conventional Commit plugin