Describing your changes to the code base is a difficult task. Especially for younger software developers.
With this guide, I want to summarize my learnings over the last couple of years.
1. Atomic Commits - one change per commit
I found, that the description isn't the greatest issue. It's the length and diversity of the changeset.
Put simply: You might have done more than one thing and struggle with describing it in one sentence.
There is a guideline called Atomic Commits which states, that each commit should have just one change.
Commit very often and describe what each commit does.
That way you won't have trouble with gigantic textes or remembering all changes you've made.
2. Define the type of the commit
There are multiple types of commits. For simplicity, I only use those four most of the time:
featdescribes changes used to introduce a new featurefixdescribes changes used to fix a bugchoredescribes everything that has to be done to keep the repo clean, set up ci, etc.testuse it, when you change the test code
If you introduce breaking changes, it's welcome to append a ! to the commit type.
3. Describe the what and why. Not the how!
Do not try to describe how you split up classes. That information should be accessible by following the diff. Describe why the change was necessary and what benefits it offers the product.
4. Always write in the present tense
Don't write added, fixed, closed.
Rather use add, fix, close in the present tense.
5. Use the commit body for ticket numbers
In my opinion, the commit headline does not need to include the ticket number. Since the ticket trackers can attach the commits themselves to the ticket.
As long as the commit body references it.
If one needs to find the ticket for a commit, they just expand the commit message.
Example commit messages
feat: add confirm dialog for task deletionfix: close functionality for dialogchore: delete .gitlab-ci.ymltest: caching only views with `shouldCache` flag
Conclusion
Don't think it's easy to always come up with the perfect commit message.
It's like writing a blog post. There will always be the potential to enhance, and so is to spend time.
Training is essential! If you learned something from the post, leave a like ❤️.