Clear Commits

How often have you tracked a bug down to a particular commit with this description:

commit 202b2afad0ed5d434618971ce2cba82203383f35
Author: Charlie <charlie@yext.com>
Date:   Tue May 26 11:48:33 2015 -0400

    switch db

It can be infuriating to have to spend time playing Sherlock Holmes when Charlie (at the time) knew exactly what change he was making and why.

Good commit messages make it easy to understand what the change does and why. Writing good commit messages supports many use cases:

  • Monitoring - All commits are broadcast to the entire team. Many engineers use this feed to stay up to date on changes to the codebase.

  • Browsing - When something breaks, it’s common to browse the commit log around the time that the breakage happened.

  • Searching - Often engineers need to refer to the changes made in response to a ticket (e.g. JIRA). Including the ID in the commit message allows you to find the commit using e.g. “git log –grep=TB-123”. Also, it allows some systems to automatically link between them.

  • Code review - The commit message is uploaded as the description on your code review, helping to provide context for the reviewer.

At Yext, we’ve codified our ideal format for commit messages in our style guide. I’ll share our recipe, starting with a rewrite of Charlie’s commit from above:

commit 5a3308cc2cb5417e8d602a85b5b6353f5fe0165a
Author: Charlie <charlie@yext.com>
Date:   Tue May 26 11:48:33 2015 -0400

    Statusboards: Use master DB for sales scoreboard

    Replication lag has caused recurring problems for the sales floor in
    getting positive feedback from their scoreboard, and running these
    queries against the master database for the last many weeks hasn't
    resulted in significant load issues on the master database.

    Along the way, also drop unnecessary use of Hibernate, and take
    advantage of some new Java 7 and 8 language features.

    Fixes techops #83283

    R=julie

Here are the key elements:

[Main component being changed]: [Short summary of change]

[Longer description of the change. 
 May include rationale for the design.
 May include issues motivating the change.]

[References to tickets addressed, e.g.
 Fixes JIRA-123
 Fixes techops #123]

R=[Reviewer]

Some changes do not require as much explanation; in those cases a one-liner can be appropriate:

commit 202b2afad0ed5d434618971ce2cba82203383f35
Author: Julie <julie@yext.com>
Date:   Thu Jun 4 19:27:58 2015 -0400

    bagmothership: Add updateUrl to venue description sent to SDK R=charlie

We’ve found that following this simple format makes it much easier for everyone to stay on the same page as our codebase and team scale up.