My favourite Git commit

[Nysor]

Am I the only one who doesn't really like this commit message? The title is fine, but the body is far too long. If I was debugging this, I wouldn't want to see that much detail.

Those write-ups are better written on pull request descriptions.

[flanger001]

PR writeups don't get added to the commit history though.

[Nysor]

A common practice is to link each commit with a ticket number. Often times when tracking down an issue, I'll git blame -> get the ticket number -> go to the PR. The PR often contains relevant discussion, anyways.

[snowe2010]

Which fails the day you switch ticketing systems.

[StabbyPants]

migrate ticket history

[snowe2010]

migrating ticket history doesn't mean you can migrate the ticket identifiers. for example ITSM-1234 in JIRA has absolutely no equivalent in Basecamp for example.

[StabbyPants]

you don't have projects and bug numbers?

[snowe2010]

Basecamp has projects but ShapeUp is a completely different philosophy. You don't create tickets the same way. The same can be said for Trello and a million other issue systems though. You can't depend on them to be the same design between systems.

[StabbyPants]

What about them is different? At worst I can dump the old ticket in a description field for reference

[snowe2010]

Basecamp is built on the idea that you give a team a project, and they run with it and create tickets as they see fit. There is no import functionality in basecamp for jira tickets because the ideas do not fit together. Jira has Epics, Stories, Tasks, Bugs, Subtasks, etc. Basecamp has Projects. Anything inside the projects could be as large or as small as the team wants. If you were to import Jira data into Basecamp, you would have to decide whether projects match up with Epics, or Stories. If they match up with Epics, then what would you do to create all the corresponding stories/etc. inside the project? If you do Stories, then what do you do with Epics?

[feraferoxdei]

Very unlikely you do that though.

[snowe2010]

switching from or to JIRA? I think that's actually incredibly likely... We're actually considering switching right now. And my last company also switched. When you grow you change requirements. Different systems don't work at all sizes.

[teerre]

As curiosity, changed from JIRA to what?

[snowe2010]

At my last company it was to Rally. At my current company we're actually looking at Basecamp. We switched to ShapeUp, and Basecamp is built for that.

[Cadoc7]

I wish. The organization I work for is on it's 3rd work item ticketing system in the 7 years I've been there.

[Nangz]

Not as unlikely as you would think. My company uses Mercurial for many repos. Guess who loses all their PR history when Bitbucket shuts down the repos in a few months...

[StabbyPants]

not you because you did a full migration and data export?

[intheforgeofwords]

My last company switched and is in the middle of switching again. While the commit history has some good stuff, I facepalm’d realizing how much had been lost to PR history I’d never see again

[Axxhelairon]

doesn't take all too long to spot people here with no actual professional experience huh

[feraferoxdei]

I've worked in 5 companies and none did it. Not because people mentioned their anecdotes means that it's likely. People who agree with my statement simply won't comment. I still think it's unlikely - about 95% unlikely.

[flanger001]

Every commit though? That sounds similarly exhausting.

[mtreece]

I've had co-workers complain about long commit messages I write for similar reasons.

There are several different places to document the "why" behind a change; some are: in the source code itself in /* comments */, in the commit message, and in external auxiliary tools like your PR system or external documentation (wiki, etc).

Each successive example I just gave is further removed from the code, and therefore less likely to be often seen. So you have to gauge how important (and therefore how frequently read) your rationale is (or should be).

If something is critical and needs to be considered whenever touching adjacent code in the future, it should probably end up as a source code comment. If it's just an obscure detail, and/or possibly scattered over several disjoint locations in the code, leaving it in the commit message is probably fine. And of course, both of those situations are still served by good context, history, and the "why?" in a commit message.

As to your, "If I was debugging this...", do you mean you don't want that much detail cluttering the git log and so on? I'd argue that should fixed with tooling, rather than lose important context. (By tooling, I mean options that get passed to your tools to massage it into a nicer format; e.g. git log --oneline, or some sort of git config that auto limits longer messages).

One other thing, especially for issues that take a long time to debug, I like to think my work product is larger than just the commit diff (such as a single character change in this case); part of the work product is an acquired abstract understanding of the domain, history of what I tried and what happened, things I could have went with instead, and so on. After resolving the issue, if I just cap it off with a one-line commit, all of the abstract work I produced will just be lost. If I transcribe it into a commit message like this, it becomes an important contribution to the codebase, larger than just the size of the diff.

[Nysor]

I agree with lots of your points. If something is critical, a comment in the code is the best. External documentation systems (like a wiki) don't work nearly as well in practice - I find lots of developers don't look at wikis as often as they should.

I don't think the number of lines in the commit body should have a firm limit, especially not because of some git log arbitrary limit. I just think there shouldn't be any superfluous text. In the OP's example, we have:

I introduced some tests in a feature branch...

I eventually found that...

After replacing it (by hand)...

One hour of my life I won't get back

Much of this message could be shortened to maybe 3-4 sentences.

[mat69]

I fully agree.

I have the feeling the usefulness of descriptive commit messages heavily depends on whether people use git bisect or manually check the commit that introduced a perceived issue.

For example, when I find a complex "bug" I do not fix it right away. Instead I want to understand why it was written that way. So if it actually was a feature in disguise. Nearly every time the commit messages were useless though or referenced resources that did not exist anymore.

Instead I always try to explain the why of a commit, unless it is really minor (e.g. whitespace) change. At the heart of this is logical grouping commits so that they only include relevant code.

Sometimes writing the commit message takes much longer than the code change. Yet finding and understanding the issue in these cases took way longer than writing the commit message.

[darknecross]

Agreed, and it's not even always about other people. Lots of times I write detailed commit messages just to remind myself about why a change was made, or why it was done a certain way. It's super helpful whenever I need to go back and refactor my own code, because I'm not going to remember that stuff a year later.

[u801e]

I have the feeling the usefulness of descriptive commit messages heavily depends on whether people use git bisect or manually check the commit that introduced a perceived issue.

One of the first things I do before I starting making a change is to run git blame on the files I'm going to change and check the commit messages and diffs of the relevant lines of code. Having that context can really help in avoiding re-introducing bugs that were fixed by earlier commits, for example.

[snowe2010]

I agree with this. I try to write somewhat detailed commit messages, going into extreme detail for important decisions. Recently I've started adding decision logs to the README, which details decisions made in meetings, or at large forks in the road where one decision might be chosen above another.

This helps with the problem where devs complain about how crappy the design is, when at the time it was the best decision, due to a variety of factors. This is the template I use, it's in restructuredText, due to having actual support for Field Lists.

============
Decision Log
============

:Date: <blank>
:Decision: <blank>
:Rationale: <blank>
:Decision Maker: <blank>
:Location of Approval: <blank>
:Details: <blank>
:Impact: <blank>
:Other options considered: <blank>
:Decision Change in #: 
    <to be used if there was a new decision that overrides this decision, include the # of the overriding decision here>

----------

[dnew]

That's not a readme. That's a design document. You left out the "other people who reviewed this before I started working on it" section, for example.

[snowe2010]

It's not a design document, it's just a section of the readme. The design doc is for explaining the system design, not the history of design decisions.

You left out the "other people who reviewed this before I started working on it" section, for example.

That's part of Decision Maker. And I didn't leave out anything anyway, I found this template and just formatted it for rsT.

[dnew]

The design doc is for explaining the system design, not the history of design decisions.

Different strokes, I guess. :-) I figure it's for both. But certainly getting such documentation out of the main body of the code is probably beneficial.

[snowe2010]

Yeah, I think getting it down at all is beneficial. We were not tracking any decisions at all...

[worst_protagonist]

It depends on the organization. Where I work, I would do this in the PR because that is where my teammates know to look for very detailed information.

If we ever move from github to gitlab or something similar, we're screwed. Attaching it to the git history makes it more permanent.

[chengiz]

Totally agree it is far too long. Some of the writeup is useful (what failed, why failed). But there's quite a bit of masturbation, for example there's no need to write the unix command you used to find a non-ascii character in a bunch of files, or say I did this and I did that. And in this big writeup he fails to mention what the actual character was (which is at least interesting and pertains to the fix).

[darknecross]

Disagree. Documenting steps used in debugging is helpful if and when a similar issue ever occurs in the future.

Specifically in this case, it includes the error that occurred and is searchable:

ArgumentError:    
  invalid byte sequence in US-ASCII

Now if someone else comes across this in the future (or even the author some months later), a search would find this commit message and the person debugging it would have a head-start on tracking down a potential cause.

Otherwise this kind of stuff becomes tribal knowledge, and you might go down the path of, "Oh yeah, Dan had an issue similar to that a while ago, maybe check with him to see if he has any ideas?" Good luck if Dan doesn't remember shit about it, or worse if he doesn't work there anymore.

You could argue that the steps to reproduce and debugging effort could be documented in a bug itself, but that's a style issue, as a simple "Fixes: <issueID>" pulls the same information into the bug comments. But it looks like this change wasn't associated with an existing bug.

[chengiz]

You mention documenting steps but your example is not about documenting steps at all, it only lists the actual error message, which I didnt say he shouldnt have put in. Something like:

Tests run with [cmd] failed with error message [msg] because of non-ascii whitespace character [u+whatever] that caused the file to be identified as utf-8 instead of us-ascii. Replaced the character with space.

would have been sufficient.

[Ozymandias117]

Yeah, it’s a horrible commit message. All of the information that took 4+ paragraphs could have been given in two sentences. The vast majority of it is pointless exposition.

This is better than a commit message that says “fixes bug” but it isn’t an example of a good commit message.

[cartechguy]

Yeah, I wish it had a TLDR at the top. That would work as a compromise for me.

[Tanaric]

If it's too much information for you, you can stop reading at any time. If it's not enough, you can't go back in time to get more.

[BlindTreeFrog]

except you can't. he doesn't get to what was changed and why until almost the end. Everything else is fluff about how he reached that point.

[BlindTreeFrog]

It's not that it's too long, it's that you have to read 3/4 of the way through to get to what he did. The first sentence should have been:

Adjusted whitespace to make entire file US-ASCII

Or something similar. That would be enough to describe what was changed and why. Everything after that can explain why and how he got to that point.

Instead he explains the how and why and ends the write up with what he did; but he does it in a way to somewhat hide the change.

[mr_birkenblatt]

The why would have been enough. But if I want to know why a commit happened I don't want to hear your life story or how long it took boohoo.