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.
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.
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.
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.
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.
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.
It’s easy to criticise, but the author isn’t exactly practicing what they preach here:
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.
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.
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.
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.