Adam Johnston

A few months back I attended the London Ruby User Group (LRUG). The LRUG is a great place for learning and it’s not always just Ruby. One such talk was entitled ‘Telling stories through your commits’ and you can watch the screencast from the meet up. I wanted to do a short piece on what I took from this talk and what has now become a part of my Git workflow and what the benefits have been.

It’s very easy to make changes to a project and simply do a commit message, you’ve probably done the following, hundreds of times:

git commit -m ‘Initial commit’

Also, if you’re like me, perhaps you’ve accidentally typed only ‘git commit’ without the message, found yourself inside of Vim, panicked, and exited as quickly as your nimble developer fingers could type :q (or ZZ). Vim can be a scary place to a developing front-ender and while I am get more comfortable using Vim on a regular basis, in the early days I had no idea what I was doing.

As part of writing more detailed commit messages, you’re going to want to get a little more familiar and comfortable with Vim, only the basics however, how to add text using insert mode, saving and quitting should be enough to get started with. Also you’re not going to want to write detailed commit messages all the time but I’ll explain when that’s the case. Firstly I want to talk about my current approach to writing a detailed commit.

Commit anatomy

Short description of changes

[Jira/Trello/Other-project-tracker]-ticketNumber or URL

* fileType        - Summary of changes
* anotherFileType - Another summary of changes

A long description explaining what the state of the project was in before you made changes, why those changes were needed and what your solution was.

This can go over several paragraphs and should include enough detail for other developers and possibly your future self to better understand why you did, what you did.

So what’s going on here? Well first we have the short description this, in essence would be what you would have written if you were using just the short Git commit message style and it should be fewer than 75 characters long.

Secondly we have the current ticket number or project tracker URL you’re working on. This is so other developers can at least refer to the issue you were tasked with and learn the need for your changes.

After that we then have a list of changes to files. What changes did you make to HTML, CSS, JS or Ruby files etc. Maybe in the HTML files you had to add a new content block and then in the CSS you added the styling for those blocks. This provides a good quick overview of the kind of changes that have been made.

Lastly, we have our long description. Here you want to talk about the context in which you found yourself. What you determined to be the cause of the issue or the need for the new feature and what you did in order to implement the changes needed. This saves you the time of having to actually explain to another developer who perhaps is code reviewing your work. Think of it more for their benefit than your own.

Here’s an example:

Added new comment boxes to pages that need them.

JIRA-0001

* HTML - Added comment boxes
* SCSS - Styling for comment boxes
* JS   - Backbone functionality for comment boxes

Our product owner required comment boxes to be added to our user profile and blog pages to better engage our users. I have added the relevant markup and styling to make the comment boxes look like our design and have added the functionality in to Backbone to have the comment boxes displayed when the user is eligible to comment and handle communication with the server.

The benefits

It’s going to take a little more time to write all this extra explanation rather than just a short description but I have found that when another developer has to code review your changes they always want to know this information. Many times I’ve been called to a fellow colleagues monitor just to explain what could have been written in a few lines.

Another benefit I see with this process is that you can also consider it a part of your documentation, a history of your development as you will and so I don’t feel like this extra overhead is a waste of a developers precious time.

It’s just a typo

What about if all you’ve done is fix a typo? that’s quite common and it still needs to be committed. Would I do the above in this regard? The short answer is, no.

git commit -m ‘JIRA-0002 — fixed typo’

This is more than enough information for a situation like this. You will need to decide when it’s best to use a short or detailed commit message but that’s a decision that I have found to be an easy one.

In summary. Using a well structured, detailed commit can help other developers understand how and why you made changes to a project and also document the history of your project. I think it is incredibly valuable to yourself and your team. I hope reading this leads you adding a similar workflow or a workflow of your own design for Git commits and you too see the benefits.

The London Ruby User Group meet every second Monday of the month and you can find out more information about them here: http://lrug.org/