DEV Community

Cover image for Mastering Conventional Git Commit Messages for Better Collaboration
Sujit Kumar
Sujit Kumar

Posted on

Mastering Conventional Git Commit Messages for Better Collaboration

#git #gitconventions

My Adventure with Conventional Commits: A Simple Guide

Hey there! I'm excited to share my journey with Conventional Commits. When I first started coding, my commit messages were a mess. But then I discovered this cool way of writing commits that changed everything for me. Let me tell you all about it!

What Are Conventional Commits?

Conventional Commits are just a fancy way of saying "a set of rules for writing better commit messages". It's like having a template for your commits that makes them easier to understand and use.

The Basic Idea

Here's the simple structure:

type(optional scope): short description

longer explanation if you need it [option body part]

any extra notes [optional footer part]
Enter fullscreen mode Exit fullscreen mode

Don't worry, I'll break this down for you!

When I started, I kept forgetting which types to use. So I made a little cheat sheet. Here are the main ones I use:
Certainly! I'll explain all the commit message types, provide examples of good and bad commit messages, and then offer some improved versions. Here's a comprehensive guide:

Understanding Commit Message Types

  1. feat: A new feature for the user or a significant addition to the application.
  2. fix: A bug fix.
  3. docs: Changes to documentation.
  4. style: Changes that don't affect the code's meaning (white-space, formatting, missing semi-colons, etc.).
  5. refactor: Code changes that neither fix a bug nor add a feature.
  6. perf: Code changes that improve performance.
  7. test: Adding or modifying tests.
  8. build: Changes that affect the build system or external dependencies.
  9. ci: Changes to CI configuration files and scripts.
  10. chore: Other changes that don't modify src or test files.

Examples of Good vs Bad Commit Messages

1. feat (Feature)

Good:

feat(auth): implement two-factor authentication
Enter fullscreen mode Exit fullscreen mode

Bad:

added new stuff
Enter fullscreen mode Exit fullscreen mode

Better:

feat(auth): add Google Authenticator integration for 2FA

- Implement QR code generation for easy setup
- Add verification step to login process
- Include user settings to enable/disable 2FA
Enter fullscreen mode Exit fullscreen mode

2. fix (Bug Fix)

Good:

fix(checkout): resolve total calculation error in cart
Enter fullscreen mode Exit fullscreen mode

Bad:

fixed bug
Enter fullscreen mode Exit fullscreen mode

Better:

fix(checkout): correct tax calculation for international orders

- Update tax rate retrieval to consider user's country
- Add unit tests for various tax scenarios
- Refactor tax calculation into separate utility function
Enter fullscreen mode Exit fullscreen mode

3. docs (Documentation)

Good:

docs: update API endpoints in README
Enter fullscreen mode Exit fullscreen mode

Bad:

changed readme
Enter fullscreen mode Exit fullscreen mode

Better:

docs(api): revise and expand API documentation

- Add examples for all endpoints
- Include rate limiting information
- Update authentication section with new token format
Enter fullscreen mode Exit fullscreen mode

4. style (Formatting)

Good:

style(global): apply consistent indentation to all files
Enter fullscreen mode Exit fullscreen mode

Bad:

prettier
Enter fullscreen mode Exit fullscreen mode

Better:

style: enforce consistent code style across project

- Apply Prettier with custom ruleset
- Adjust ESLint config to align with new style guide
- Update CI to fail on style violations
Enter fullscreen mode Exit fullscreen mode

5. refactor

Good:

refactor(database): optimize user query for better performance
Enter fullscreen mode Exit fullscreen mode

Bad:

cleaned up code
Enter fullscreen mode Exit fullscreen mode

Better:

refactor(user-service): improve efficiency of user data retrieval

- Replace multiple database calls with single aggregated query
- Implement caching layer for frequently accessed user data
- Update related services to use new optimized methods
Enter fullscreen mode Exit fullscreen mode

6. perf (Performance)

Good:

perf(images): implement lazy loading for product images
Enter fullscreen mode Exit fullscreen mode

Bad:

made site faster
Enter fullscreen mode Exit fullscreen mode

Better:

perf(front-end): optimize initial page load time

- Implement code splitting for React components
- Set up lazy loading for below-the-fold content
- Minimize and compress all static assets
Enter fullscreen mode Exit fullscreen mode

7. test

Good:

test(api): add unit tests for user registration process
Enter fullscreen mode Exit fullscreen mode

Bad:

added tests
Enter fullscreen mode Exit fullscreen mode

Better:

test(auth): expand test coverage for authentication module

- Add unit tests for password reset functionality
- Implement integration tests for OAuth flow
- Set up mock server for third-party auth provider testing
Enter fullscreen mode Exit fullscreen mode

8. build

Good:

build(deps): upgrade to React 18
Enter fullscreen mode Exit fullscreen mode

Bad:

updated packages
Enter fullscreen mode Exit fullscreen mode

Better:

build: migrate from Webpack to Vite for faster builds

- Configure Vite for development and production environments
- Update npm scripts for new build process
- Adjust CI pipeline to accommodate Vite builds
Enter fullscreen mode Exit fullscreen mode

9. ci (Continuous Integration)

Good:

ci(travis): add automatic deployment to staging environment
Enter fullscreen mode Exit fullscreen mode

Bad:

updated ci
Enter fullscreen mode Exit fullscreen mode

Better:

ci: implement comprehensive CI/CD pipeline with GitHub Actions

- Set up automated testing for PRs
- Configure staging deployment on merge to develop branch
- Implement production deployment process for tagged releases
Enter fullscreen mode Exit fullscreen mode

10. chore

Good:

chore: update .gitignore to exclude .env files
Enter fullscreen mode Exit fullscreen mode

Bad:

misc changes
Enter fullscreen mode Exit fullscreen mode

Better:

chore(project): streamline development setup process

- Create detailed CONTRIBUTING.md with setup instructions
- Add .env.example file with required environment variables
- Update package.json with helpful npm scripts for common tasks
Enter fullscreen mode Exit fullscreen mode

Commit message with footer 

feat(user-profile): add ability to upload profile picture

- Implement image upload functionality
- Add image cropping and resizing options
- Create new API endpoint for image upload

BREAKING CHANGE: This update requires a new 'images' table in the database.
Reviewed-by: Sujit
See-also: #123, #456
Closes: #789
Enter fullscreen mode Exit fullscreen mode

Tips I Learned the Hard Way

  1. Be clear about what you did. Future you will thank present you!
  2. Keep the first line short - aim for 50 characters or less.
  3. Use simple language. Pretend you're telling a friend what you did.
  4. If you're fixing a bug or implementing a feature, mention the issue number if you have one.

Why I Love Conventional Commits

  1. It's easier to find things in the project history.
  2. It helps me think clearly about what I'm committing.
  3. My team can understand my changes without asking me a million questions.
  4. We can automatically generate changelogs and version numbers.

Oops! I Made a Mistake

Don't panic! We all make mistakes. If you used the wrong type and haven't pushed your commit yet, you can fix it:

  1. Use git commit --amend to change your last commit message.
  2. If it's an older commit, use git rebase -i or git rebase -i HEAD~n (replace n with the number of commits to go back), then change pick to reword for the commit you want to fix.

If you've already pushed, it's usually best to just make a new commit with the correct message. Learn and move on!

Wrapping Up

Adopting Conventional Commits was a game-changer for me. It made my commits clearer, helped my team work better together, and even made me think more carefully about my code changes.

Start small, be consistent, and don't worry if you make mistakes at first. Before you know it, you'll be a Conventional Commit pro!

Have you tried Conventional Commits? I'd love to hear about your experiences. Drop a comment below and let's chat!

Happy coding, everyone! 😊

Top comments (0)

Read next

pinotattari profile image

Attaching notes to git branches

Riccardo Bernardini -

chishengliu profile image

The Ultimate Guide to Git for Open-Source Development

Chi-Sheng Liu -

vaunt profile image

GitHub for Beginners: A Step-by-Step Guide

Vaunt -

danteon profile image

Building Your Discord Bot with Discord.js v14: A Quick Start Guide ⚡️

Danteon -