This is a pretty simple topic, but one that I find really important. It’s also something I’m pretty proud of that we do on my team… take the time to write good commit messages. Additionally, we always try to create pull requests with descriptions that make it easy for any developer to know exactly what was done and why. This makes it easy for a new developer contributing to the project or even a seasoned developer changing old code to understand why things were done previously.

When I first started writing code and using Git, I would write commit messages that weren’t the most descriptive. It wasn’t until I worked on a team at a previous company that I had a senior developer who stressed how important it is to write good commit messages and shared this article with me from Chris Beams.

Beam goes into some tips or as he calls them, rules, in more detail on his blog post, but some some that I think help you make the most of your commit messages are to treat the first line of a commit as the subject line, which is a brief 50 character max description of the code, and then, after a line break, writing a body that is more explanatory about the code. You can add additional paragraphs for different parts you want to explain.

  Summarize changes in around 50 characters or less

  More detailed explanatory text, if necessary. Wrap it to about 72
  characters or so. In some contexts, the first line is treated as the
  subject of the commit and the rest of the text as the body. The
  blank line separating the summary from the body is critical (unless
  you omit the body entirely); various tools like `log`, `shortlog`
  and `rebase` can get confused if you run the two together.  
  
  Explain the problem that this commit is solving. Focus on why you
  are making this change as opposed to how (the code explains that).
  Are there side effects or other unintuitive consequences of this
  change? Here's the place to explain them.

The above example is what I generally follow and try not to just explain what was changed, but why, since anyone can read the code but might not understand from the code itself why a specific change or decision was made.

As for pull requests, since I generally squash my commits to make a single commit, I end up with one commit message that covers all the changes that were made and why. This is generally what I use for my description in the PRs since it covers everything that I did.

On our team, we add some extra stuff to our PRs, which just adds more information and adds a little fun to it. You don’t have to do these, but it’s nice to have. We generally link to the ticket for the changes or feature requested, add some tasks to do such as installing new packages, if the version was bumped, add screenshots and short video demonstrations, plus a little gif, usually from Giphy, at the end that just sort of summarizes the PR. It’s something fun, especially if you went down a ton of rabbit holes to arrive at your solution.

alt text

To make all these easier for your PRs, I definitely recommend adding a pull request template on Github or wherever you host your code. It makes it much easier for PRs to all follow a similar format. Github has a guide to help you do it here.

I hope some of these tips will help your team be more efficient in communicating in your projects.