It can be tough for your team to know exactly why they need the changes you’re proposing in a pull request. What if we could give them more context? There’s an episode of The Weekly Iteration where a simple trick was mentioned. After adopting it myself, I have noticed my co-workers commenting on how useful these messages have been in providing context.

The trick is simple. Split your PR message into two sections:

Some awesome title Why: * ... This change addresses the need by: * ...

Starting with this structure forces you to answer why the change is necessary before outlining the changes that you have made towards this goal.

We can tell git to setup our commit messages with this structure. This is done by setting commit.template in ~/.gitconfig :

[ commit] template = ~/.gitmessage

Then create ~/.gitmessage with our new default: