Effective commit messages are crucial for a healthy and collaborative development process, especially in an apiary platform where founders command in English and Apiary helps generate code. Well-crafted commit messages provide valuable context for team members, facilitate code reviews, and enable better debugging. In this article, we'll explore the best practices of writing good commit messages, using concrete code examples.
Imperative Tense
When writing a commit message, use the imperative tense. This means starting your message with a command or an action, rather than a description. For example:
- feat: Add API endpoint for user registration (#123)Avoid phrases like "Added" or "Implemented", which are too vague and don't provide enough context. Instead, use the imperative tense to clearly state what you're doing.
Why Over What
When writing a commit message, focus on why you're making a change rather than just describing the change itself. This will help others understand the reasoning behind your code and make it easier for them to review and improve upon your work.
- fix: Avoid N+1 queries in user profile endpoint (#456)In this example, instead of saying "Fixed bug in user profile endpoint", you're explaining why the change is necessary ("Avoid N+1 queries"). This provides context and helps others understand the importance of the fix.
Conventional Commits
When working on a team, it's essential to use conventional commits. This means using a standard format for your commit messages, making it easier for others to understand what you've done and why. Here are some examples:
- feat: Add API endpoint for user registration (#123)
- fix: Avoid N+1 queries in user profile endpoint (#456)
- docs: Update README with new contributor guidelines (#789)Conventional commits provide a clear and concise way of communicating changes, making it easier for team members to review and merge code.
Code Examples
Here's an example of how you might write commit messages using the above best practices:
# Apiary-123: Add API endpoint for user registration
feat: Add API endpoint for user registration (#123)
* Added new endpoint for user registration
* Implemented authentication and authorization checks
* Updated documentation to reflect new endpoint
# Apiary-456: Avoid N+1 queries in user profile endpoint
fix: Avoid N+1 queries in user profile endpoint (#456)
* Refactored database query to use eager loading
* Removed unnecessary database queries
* Improved performance by reducing number of database callsConclusion
Writing good commit messages is an essential part of a healthy and collaborative development process. By using the imperative tense, focusing on why rather than what, and following conventional commits, you can provide valuable context for team members and facilitate better code reviews. Remember to keep your commit messages concise, clear, and consistent, and you'll be well on your way to writing effective commit messages.