Best practices on Commit Messages

For large teams and automated tooling, the Conventional Commits standard is recommended. It offers advantages like:

• Changelogs and release notes can be generated automatically.
• Tools like semantic-release can bump major/minor/patch versions automatically.
• Developers instantly know the commit type.
• Easier onboarding for new contributors.

The syntax:

<type>[optional scope]: <short description>
<BLANK LINE>
[optional longer description or context]

<type> values:

1. feat: — a new feature.
2. fix: — a bug fix.
3. docs: — documentation changes.
4. style: — code style changes (no logic changes).
5. refactor: — code changes that neither fix nor feature.
6. perf: — performance improvements.
7. test: — adding or updating tests.
8. build: — changes to build system or dependencies.
9. ci: — changes to CI/CD configuration.
10. chore: — maintenance tasks (no production code changes or changes that don't modify src or tests).
11. revert: — revert a previous commit.
12. security: — security-related fixes.
13. config: — configuration/environment changes.
14. release: — tagging/releasing.

1. Features (feat)

feat(auth): add user login feature
feat(ui): introduce dark mode toggle
feat(api): implement pagination for blog posts
feat(dashboard): customize widgets for user dashboard
feat(localization): support multiple languages in settings

2. Bug Fixes (fix)

fix(homepage): correct broken image link
fix(auth): resolve race condition in token refresh
fix(ui): adjust padding on mobile view
fix(security): sanitize user inputs to prevent SQL injection

3. Documentation (docs)

docs(api): document new endpoints for user management
docs(readme): revise setup instructions for local environment
docs(config): clarify usage of environment variables

4. Style (style)

style(css): polish buttons for better mobile responsiveness
style(lint): reformat code to comply with lint rules
style(imports): sort imports alphabetically

5. Refactoring (refactor)

refactor(auth): restructure authentication service for better readability
refactor(api): simplify query building logic
refactor(ui): tidy up component structure

6. Performance (perf)

perf(images): optimize image assets for faster loading
perf(api): cache responses for 24 hours
perf(database): add index to improve query performance

7. Tests (test)

test(auth): add unit tests for login flow
test(profile): mock database for faster test execution
test(api): verify correct behavior of search results

8. Build (build)

build(deps): bump react to v18.3.0
build(docker): configure multi-stage build for smaller image size

9. CI (ci)

ci(github): automate deployment pipeline with GitHub Actions
ci(test): ensure tests run on pull requests

10. Chore (chore)

chore(cleanup): remove unused CSS classes
chore(config): update environment variables for new API keys
chore(repo): organize utility functions into separate modules

11. Revert (revert)

revert(auth): revert commit 123abc that broke login

12. Security (security)

security(auth): encrypt passwords with bcrypt
security(api): restrict file upload types to only images

13. Config (config)

config(env): add DATABASE_URL to .env.example
config(docker): add multi-stage build to reduce image size
config(ci): update GitHub Actions workflow to run E2E tests
config(k8s): increase api deployment cpu/memory limits
config(helm): bump chart values to use new image tag
config(terraform): add s3 bucket and lifecycle policy for logs
config(nginx): add gzip compression and caching headers
config(flags): enable new-checkout-feature behind feature flag
config(logging): switch to JSON-formatted logs for ELK ingestion
config(biome): add new rule to format with semicolon

14. Release (release)

release: v2.0.0

Example Commit Message

feat(api): implement user profile caching
 
Add Redis caching to user profile endpoint to improve response
times and reduce load on the database. Cache expires after 5
minutes and is invalidated on profile update.
 
Fixes #456

Example Workflow

Here’s how you’d write commits while developing a feature:

feat(auth): add Google OAuth login
docs(auth): update README with OAuth setup instructions
fix(auth): handle token refresh failure
test(auth): add unit tests for OAuth token exchange

When merged, a tool like semantic-release could:

• See feat: → bump minor version.
• See fix: → bump patch version.
• Generate a changelog grouping all commits by type.

Useful Verbs

Here’s a list of verbs that are commonly used to start Git commit messages. They are structured to be in the imperative mood, which is the best practice for writing commit messages.

General Changes

• Add
• Update
• Remove
• Refactor
• Fix
• Improve
• Modify
• Change
• Create
• Delete
• Implement
• Optimize
• Replace

Feature-Specific Changes

• Introduce
• Enable
• Disable
• Build
• Develop
• Extend
• Enhance
• Support
• Provide
• Migrate
• Simplify
• Customize

Bug Fixes / Error Handling

• Correct
• Resolve
• Address
• Handle
• Repair
• Prevent
• Patch
• Overhaul

Testing / Validation

• Test
• Validate
• Verify
• Ensure
• Check
• Assert
• Mock
• Remove
• Create (tests)

Documentation

• Document
• Write
• Clarify
• Update (documentation)
• Add (comments)
• Revise

Code Structure / Formatting

• Organize
• Restructure
• Reformat
• Cleanup
• Simplify
• Polish
• Tidy
• Sort
• Standardize
• Align
• Group

UI / UX Specific

• Design
• Style
• Align
• Improve (UI/UX)
• Redesign
• Adjust
• Fix (layout)
• Enhance (accessibility)

Configuration / Environment

• Configure
• Set
• Update (configuration)
• Add (environment variables)
• Initialize

Performance

• Optimize
• Speed up
• Cache
• Reduce
• Compress
• Decrease (memory usage)
• Improve (performance)

Security

• Secure
• Protect
• Encrypt
• Sanitize
• Harden
• Restrict
• Authorize

Version Control

• Bump (version)
• Revert
• Merge
• Squash
• Cherry-pick
• Sync
• Tag
• Resolve (conflicts)

Deployment

• Deploy
• Release
• Publish
• Automate
• Ship

Miscellaneous

• Remove (dead code)
• Add (dependencies)
• Exclude
• Introduce (new pattern)
• Remove (warnings)
• Track
• Untrack
• Split
• Consolidate