Write commit messages with the future in mind

Want to write more helpful commit messages?

Write with the future in mind, and you’ll also write better messages for the present.

Write autonomous commits

Include all relevant information in the commit itself. Don’t rely on external systems.

It’s good to include a link to the relevant ticket for Pivotal, Trello, Jira, etc. But don’t stop there. Future developers may not have access to your team’s issue tracker. I’ve seen teams change issue trackers and lose all of their commits’ context because they only linked to the ticket. Instead, include the context in the commit itself – you can even copy the information from the issue tracker and paste it into the commit message.

The only exception?

Linking to other commits (not Pull Requests – commit SHAs). Developers can always git show SHA to get the related commit’s context.

Write the why as well as the what (and possibly the how)

Don’t just say what you did. Always include why you did it.

Most people only mention what they changed. And though it’s helpful, it’s also the least important part – we can deduce that from the code changes. But the why is usually lost across time.

And if you went on a journey to solve the problem, describe how you arrived at the solution and how it solves the problem. It might be obvious to you now, but it won’t be to those reading the commit in the future.

Write quotes for those links

Linking to external documentation is great. But external documentation can also change with time.

If a change in documentation can lose the context you’re linking to, copy the crucial context in a quote:

We use [start_supervised/2] because it's recommended:

> The advantage of starting a process under the test supervisor is that
it is guaranteed to exit before the next test starts.

[start_supervised/2]: https://hexdocs.pm/ex_unit/main/ExUnit.Callbacks.html#start_supervised/2

Remember, we want our commit to be a time capsule – capturing all the necessary information at a point in time.

Write to be discovered

Ask yourself when and why someone might need your commit in the future.

Don’t think only about describing the changes for your team with all their present context. Instead, think of someone in the future searching for information:

• Why might they be trying to get to the work you just finished?

• What words would they be searching for?

• How can the title reveal this is the right commit to look into?

Write so your commit can be found.