1. 22

  2. 6

    I’ve spent the last couple of years porting and implementing a backend for GCC and not having useful commit messages is a serious drag. I’ve also found that Changelog messages are essentially useless. When there’s no context or discussion around why a change was made, I’m left to dig through the mailing list in hopes it was discussed there (it usually isn’t). If GCC committers followed the advise here (the formatting stuff is less important), I’d probably have fewer problems. (*)

    At work, each commit is supposed to be tied to a ticket/issue number in the issue tracking software. This seems like excessive ceremony, but it pays off in the long run because you can actually track down reasoning behind a decision months later when something goes wrong related to what you are investigating. I think having an issue number is about as good or better than a descriptive commit message.

    (*) More recent GCC commits are better about writing useful commit messages, I must admit.

    1. 7

      Instead of writing commit messages like:

      Fix mobile width issue

      We want to write commit messages like:

      Fix mobile width issue

      It seems that the various ‘edit’ links under the headers were right aligned and with some margin or negative margin (from the ‘row’ class) that was causing it to push out beyond the edge of the page on mobile leading to a weird space down the right.

      This seems to address it and uses flexbox instead of float right, I suspect the first pass of this site didn’t use flexbox for fear of compatibility issues but we can certainly use it now.

      Is it perfect? No, but it provides much more context, explanation and reasoning.

      It’s easy to criticise, but the author isn’t exactly practicing what they preach here:

      Further content

      Yeah, yeah. Should be a better commit message. Just read the changes.

      Editing pass

      Add further content to piece

      Further editing and examples

      Further edits

      Further edits

      Further editing and examples

      Further additions, edits & formatting

      It’s true that most of these changes don’t warrant an extended explanation of why the change was made, so instead of advocating for extended explanation in every commit message, perhaps it would be better to focus on at least trying to make the commit message identifiable, so that someone looking through the commit history can find the relevant commits easily.

      1. 6

        I think your comment is a bit pedantic, It’s clear the author just understood who the audience of the commit log of this repository is, it’s him. He doesn’t need to over explain changes when it’s copy editing a document that virtual no one is going to sincerely need to dive into the history of. Using that to try to dismiss the message is disingenuous.

        Commit messages are so often overlooked, but are consistently one of the most useful things when looking at a bug or trying to track down an issue. The intent and context of a change is so valuable when you are debugging why something broke. I’m all for this article and the numerous other articles which promote that we all should take them more seriously and put far more genuine effort into writing them. It’s a required skill IMHO.

        1. 4

          I believe that takes discipline but also experience. I still have hard time making truly atomic commits, but these days I usually write big and explanatory commit messages… so much so that I link the commit at the repo’s README many times. But this is because too many times in the past I wasn’t able to remember what is did there.. or why. Some times I had no idea that commit was mine and I don’t suffer from memory loss… so I am basically talking to my future self ELI5 style. Not always, occasionally there is the “Fix typos” commit ofc. But when I do bigger changes I try to add as much context as possible.

          1. 3

            I think your first paragraph is spot-on. Moreover, code and prose are different things and it shouldn’t be surprising that the best practices for a repo full of code are different from those for a repo full of text.