Committed to Good Commits: Work Item Association

This is part of a series on good commits.

Ok, Mr. Anderson⌗

@druttka Dude. When you gonna finish your "Committed to Good Commits" series?

— Will Anderson (@itsananderson) February 22, 2015

Work Item Association⌗

Another way to enhance your commits is to associate them to work items. This can help everyone on the team - present and future - understand what’s going on with the project.

What Are You Doing?⌗

One of the most common problems I see during code reviews is that reviewers do not have a proper context for what they’re reviewing. Things devolve into something on par with copy editing with no feedback on the plot. At best, bad loops or off by one errors get caught, but there are no guarantees that the changes are covering all of the intended acceptance criteria.

What if the author could give the reviewers a pointer to something that explained what they were trying to accomplish? Something that was already on record in a shared system? Something like a work item?

How Did We Fix That?⌗

Another great advantage of associating commits to work items is to jog memories when the ghosts of crushed bugs come back to haunt the team.

Have you ever come across a problem and thought, “This seems familiar. We fixed something like this a while ago. I just can’t remember how…”

Or, “This is a regression of what we fixed a few weeks ago, but I don’t remember exactly what we did to fix it.”

What if you could look at the old bug and know exactly which commits resolved the issue? What if you could just grep a git log for an issue number?

Test Case Generation⌗

It can also help a test team understand what areas are at risk for regression if they know what code is changing. Put commit information on the bug when you resolve it so that they can review the changes.

Common Arguments⌗

1. “We don’t use issue tracking."¹ In this case, you can use the extended commit message to provide a lot of details of what your change is attempting to do.
2. “I forgot!” This, like many things in this series, is just a matter of habit. The team can hold each other accountable, or you can find a way to enforce it via policy.
3. “Takes too long!” Again, like many things in this series, compare it to the time spent on the change itself and to the time that will be wasted later (looking things up, discussing the intent of the code review, etc.). Seconds on hours is blue on black².

Thoughts?⌗

What do you think? Is adding this extra information to the public record of your project history valuable? If not, why not? If so, what other benefits have I missed? What else can we do to make it more natural for our teams?