Conventional Commits

Prasanth

3 min read

·

Jul 14, 2026

--

Listen

Share

Instead of writing vague commits like "updated button", Conventional Commits use a structured format that makes your project history clean, searchable, and easy for other developers (or your future self) to scan. As a massive bonus, it also allows automated tools to generate change logs and determine semantic versioning updates automatically.

Here is the structured breakdown of the standard prefixes, when to use them, and real-world examples.

Press enter or click to view image in full size

feat (Features)

• Use Case: Use this when you are adding brand new functionality to the codebase. If a user can do something they couldn’t do 5 minutes ago, it’s a feat.
• Examples:
• feat: add Apple OAuth sign-in option to login page
• feat: implement dark mode toggle in navbar

fix (Bug Fixes)

• Use Case: Use this when you are correcting a bug, crash, or broken behavior in the application.
• Examples:
• fix: resolve crash on checkout when payment token is null
• fix: prevent duplicate form submissions on double-click

chore (Routine Maintenance)

• Use Case: Use this for background tasks that don’t modify frontend features or backend application logic. This includes updating build scripts, dependencies, config files, or directory structures.
• Examples:
• chore: bump lodash dependency from 4.17.20 to 4.17.21
• chore: update firebase.json CSP headers to allow Google login
• chore: add ignore rules to .gitignore

docs (Documentation)

• Use Case: Use this when you are only changing text files that describe how the project works, such as READMEs, setup guides, API docs, or code comments.
• Examples:
• docs: update installation instructions in README
• docs: add JSDoc comments to payment processing function

style (Formatting & Visual Cleanliness)

• Use Case: Use this for changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, linting fixes).
• Note: If you are changing the visual CSS design of a button, that is usually a feat or refactor. style is strictly for code formatting.
• Examples:
• style: run Prettier to fix code indentation across src/
• style: add missing semicolons in auth controller

refactor (Code Restructuring)

• Use Case: Use this when you are rewriting code to make it cleaner, faster, or more readable without actually changing what it does or adding a feature.
• Examples:
• refactor: convert class components to functional React components
• refactor: simplify nested if-else conditions in authentication helper

test (Testing)

• Use Case: Use this when you are adding new tests or correcting existing tests. No production code changes are involved here.
• Examples:
• test: add unit tests for user validation helper
• test: fix flaky Cypress integration test for payment gateway

The Golden Rules of writing the commits

Keep it lowercase: Start the description after the : with a lowercase letter.

Use the imperative mood: Write it as if you are giving a command.

• Good: feat: add button
• Bad: feat: added button or feat: adding buttons

No period at the end: Keep it brief and don’t end the summary line with a .

The Scope (Optional but highly recommended)

Adding a scope in parentheses helps pinpoint where the change happened.

• feat(auth): add google sign-in
• fix(api): correct payload size limit

Advanced: Breaking Changes ⚠️

If a change you make will break existing functionality (like changing an API endpoint parameter structure or deleting a database column), you must signal a Breaking Change so developers are warned. You do this by adding an exclamation mark ! before the colon:

• feat(api)!: remove support for version 1 authentication endpoints
• refactor(database)!: drop legacy billing address columns

Stay updated with the latest insights and tutorials by following me on Medium and LinkedIn. For any inquiries for games or questions, feel free to reach out to me via email. I’m here to assist you with any queries you may have!

Don’t miss out on future articles and tips!