Commit Logs vs. External Systems

There’s a couple of schools of thought on commit logs: should you make them detailed, or should they be little more than a pointer to some sort of external pull request, ticketing, or ALM system?

When people have external systems, the basic problem they face is that those systems seem to be redundant with the information in the commit log.  Why write the same thing twice, when the commit log can just point to the ticket, which undoubtedly has a lot of rationale and reasoning already written into it?

But in my experience, it’s far more useful to have good commit log messages. When hunting in the code for a problem, the commit log is right there and available to tools like git log --grep, which can also print the diff alongside the log messages.

And while some tools like GitHub pull requests offer line-by-line commentary on diffs, the other interesting thing about commit logs is that they’ve proven much more resilient over time.  Our ticket tracking has migrated from my boss’s inbox, to Lighthouse, to a bespoke ticketing system… that we integrated into our support team’s workflow as well, which has become something we want to split back out.  And then we might replace the “remaining half” of the bespoke system with some off-the-shelf solution.

Meanwhile, our commit logs have been preserved, even across a move from subversion to git, so those go back to the point in time where the founders realized they should set it up.  But the references to “Lighthouse” have been broken for years, and if we succeed in killing a huge pile of custom code nobody wants to maintain, all those “ticket #16384” references are also going to be useless.

But the commit messages will live on, in a way that ticketing systems have not.  And so, I don’t really trust that we’d stick to GitHub and have their issue and pull request systems available for every change, forever.

Aside from that, I think a succinct summary of the ticket makes a good commit message.  I try to avoid repeating all the ticket babble, status updates, and dead ends in the commit:

Contoso requested that their cancellations be calculated on a 90-day cliff instead of days remaining in term.  Add cancel_type=cliff and cancel_cliff_days=90 to the client settings.  Ticket 18444.

This gives the big-picture outlook on what happened and why, and lets the diff speak for itself on whether the change suits the intention.  If there are questions about whether the true intention was understood, then the ticket is still linked, so it can be examined in further detail.

The Pain of Not Knowing

We’ve been rewriting a site with React, which I never actually looked very deeply into.  I heard it was a “framework” and expected it to be, more or less, Client Side Rails.  So I assigned it, things happened, and many surprises were had.

One of them was that, in thinking about React as a framework, I missed the need to specify that it should act like it belongs on the Web, with linkable pages, and stuff.  We got to the end of the road and the developer was surprised that completely lacking deep links wasn’t what I had wanted or expected.

This confused me, because we have another site that we’ve been wanting to rewrite for a while.  There’s a decent list of complaints about it, and I thought he understood them, especially that it’s a single-page app written in one huge mass, that never updates the URL bar.  There aren’t any seams to pull it apart and replace things gradually.

I guess not, because he wrote this auxiliary system as a single-page app in one huge mass, that never updates the URL bar.  It took us nine months or so to get this result, and something so fundamental as request routing would basically require a rewrite.  Which I don’t think we have time for, and besides, the developer is burning out on frontend work as it is.

tl;dr: you can’t actually manage what you don’t understand.  Or you can try, but it’s going to be incredibly inefficient.