My 5 tips for writing killer commit messages

My 5 tips for writing killer commit messages

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:

  • feat describes changes used to introduce a new feature

  • fix describes changes used to fix a bug

  • chore describes everything that has to be done to keep the repo clean, set up ci, etc.

  • test use 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

  1. feat: add confirm dialog for task deletion

  2. fix: close functionality for dialog

  3. chore: delete .gitlab-ci.yml

  4. test: 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 ❤️.

Read more