One thing that is overlooked and under rated in team projects and especially open source collaboration is a good commit message and the benefits that come from that good commit message. Writing a good commit messages will be the difference between understanding the changes and needing to see the diff to understand the changes. Consider the following commit message:
[project/master_branch] updated database configuration parameters
Ok, so the database configuration parameters were updated, simple? Not exactly.
From this commit message we cannot understand why the commit was made or the scope of the issue that it resolved. Sure, it could just be a single one-off database parameter change or it could be another issue in another part of your project.
Want the solution? Write a better commit message. Here is an example of a good commit message and I will explain why in just a moment.
Updated database configuration parameters for new user
Changed the user credentials for database connection since 'user_123' is no
longer an available SQL user account.
Now everyone that reads this commit will know why the commit was made as well as now understanding the scope of the issue that was resolved and how this issue could effect other parts of your project.
Tips for writing good commit messages
The commit message
- Use the first line to sum up the change
- Leave an empty line (this is a formatting nicety for many clients)
- Explain the commit in detail (what was involved in the commit, what the new feature does, etc)
- Reference tickets, support lines if they were involved.
General
- Format the commit message to be no more then 80 characters long. This will help readability and not require horizontal scrolling in many clients.
- Don’t use “misc changes” or something similar as a commit message. It defies every rule previously mentioned.
- If you cannot look back 5 years from now and understand why the commit was made, you have not wrote a good commit message.