This content originally appeared on DEV Community and was authored by Sujit Kumar
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]
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
- feat: A new feature for the user or a significant addition to the application.
- fix: A bug fix.
- docs: Changes to documentation.
- style: Changes that don't affect the code's meaning (white-space, formatting, missing semi-colons, etc.).
- refactor: Code changes that neither fix a bug nor add a feature.
- perf: Code changes that improve performance.
- test: Adding or modifying tests.
- build: Changes that affect the build system or external dependencies.
- ci: Changes to CI configuration files and scripts.
- 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
Bad:
added new stuff
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
2. fix (Bug Fix)
Good:
fix(checkout): resolve total calculation error in cart
Bad:
fixed bug
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
3. docs (Documentation)
Good:
docs: update API endpoints in README
Bad:
changed readme
Better:
docs(api): revise and expand API documentation
- Add examples for all endpoints
- Include rate limiting information
- Update authentication section with new token format
4. style (Formatting)
Good:
style(global): apply consistent indentation to all files
Bad:
prettier
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
5. refactor
Good:
refactor(database): optimize user query for better performance
Bad:
cleaned up code
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
6. perf (Performance)
Good:
perf(images): implement lazy loading for product images
Bad:
made site faster
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
7. test
Good:
test(api): add unit tests for user registration process
Bad:
added tests
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
8. build
Good:
build(deps): upgrade to React 18
Bad:
updated packages
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
9. ci (Continuous Integration)
Good:
ci(travis): add automatic deployment to staging environment
Bad:
updated ci
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
10. chore
Good:
chore: update .gitignore to exclude .env files
Bad:
misc changes
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
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
Tips I Learned the Hard Way
- Be clear about what you did. Future you will thank present you!
- Keep the first line short - aim for 50 characters or less.
- Use simple language. Pretend you're telling a friend what you did.
- If you're fixing a bug or implementing a feature, mention the issue number if you have one.
Why I Love Conventional Commits
- It's easier to find things in the project history.
- It helps me think clearly about what I'm committing.
- My team can understand my changes without asking me a million questions.
- 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:
- Use
git commit --amendto change your last commit message. - If it's an older commit, use
git rebase -iorgit rebase -i HEAD~n(replace n with the number of commits to go back), then changepicktorewordfor 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! 😊
This content originally appeared on DEV Community and was authored by Sujit Kumar
Sujit Kumar | Sciencx (2024-07-22T05:02:08+00:00) Mastering Conventional Git Commit Messages for Better Collaboration. Retrieved from https://www.scien.cx/2024/07/22/mastering-conventional-git-commit-messages-for-better-collaboration/
Please log in to upload a file.
There are no updates yet.
Click the Upload button above to add an update.