5 ms·

The "rule" I like when it comes to commit messages it that they should be clear enough that someone who gets woken up for a production issue at 3am can quickly

The "rule" I like when it comes to commit messages it that they should be clear enough that someone who gets woken up for a production issue at 3am can quickly parse what was in the commit and how dangerous it is. Nothings worse than digging through a ton of diffs to find the breaking change.

beatgammit 7y ago
Yup. I follow the kernel commit message guide, since it seems pretty reasonable. It's basically: 1. really short summary in a few words, ideally mentioning the relevant issue(s) in the bug tracker 2. Blank line 3. Longer message, if necessary, to explain the change If I'm going to be looking back through commit messages, that's the type of commit message I want to read. I want to know whether this commit is interesting or if I can safely skip it. It doesn't need to be complicated. Just write a short note as if you wanted to remind yourself where you left off when you come back from vacation.
- em-bee 7y ago
  another use for commit messages is to document learning. when we figured out how to avoid a certain type error in typescript, we made sure to describe it in a way that we would find it again, or it would come up in a search.
bagacrap 7y ago
yeah althouggh looking at touched files tends to be a heck of a lot more helpful IME especially if you have a stack trace
lmm 7y ago
I find that requiring "nice" commit messages tends to mean digging through bigger diffs to find the breaking change. If you're fine with commit messages like "fix" or "derp", then people are more willing to make each tiny change a separate commit, and then a git bisect takes you right to the specific diff that caused the problem.
- em-bee 7y ago
  that is an interesting argument, but i don't quite buy it. the commit history is used for other things too, not just to find bugs using bisect. if that was the case we would not need any commit messages in the first place. how much effort does it take to explain the change in a sentence? if it is a small change then it also will be a small commit message. the commit message doesn't need to be nice, but it should be descriptive.
  - lmm 7y ago
    > the commit history is used for other things too, not just to find bugs using bisect. Is it? People assume this, but I'm not convinced they use it for anything else in practice. > if that was the case we would not need any commit messages in the first place. I'd be interested in a VCS that followed through on this. Give PRs messages, maybe have some way to attach messages to tags, but permit individual commits to be anonymous. > how much effort does it take to explain the change in a sentence? if it is a small change then it also will be a small commit message. More effort than writing the change, often enough. In a high-quality codebase the code change should speak for itself. (And if it doesn't, you may well end up needing an explanatory comment in the code anyway).
    - em-bee 7y ago
      In a high-quality codebase the code change should speak for itself. (And if it doesn't, you may well end up needing an explanatory comment in the code anyway). that is indeed pretty much true. in that sense the commit message is just helping me to avoid needing to look at the diff. an outline of the commits. related to the PR, it would then be interesting to annotate groups of commits. a sequence of commits that make up a PR, but even without depending on the current PR mechanism (which at least in git is not stored anyways, so we need something to fill that gap) tags don't fit that, as they annotate a single commit, and we'd get to many tags that way. some other mechanism is needed to allow treating a series of commits as a unit.
- pjc50 7y ago
  Absolutely not! Submitting "derp" to code review is just disrespectful of the reviewer's time. There's a rationale for every change. The submitter knows it. The reviewer needs to know it. They can try reconstructing it from the diff, which is potentially error prone .. or you could just tell them. I'll accept "Fix ticket #1234", since that's moved the rationale elsewhere.

beatgammit 7y ago

Yup. I follow the kernel commit message guide, since it seems pretty reasonable. It's basically: 1. really short summary in a few words, ideally mentioning the relevant issue(s) in the bug tracker 2. Blank line 3. Longer message, if necessary, to explain the change If I'm going to be looking back through commit messages, that's the type of commit message I want to read. I want to know whether this commit is interesting or if I can safely skip it. It doesn't need to be complicated. Just write a short note as if you wanted to remind yourself where you left off when you come back from vacation.

em-bee 7y ago
another use for commit messages is to document learning. when we figured out how to avoid a certain type error in typescript, we made sure to describe it in a way that we would find it again, or it would come up in a search.

bagacrap 7y ago

yeah althouggh looking at touched files tends to be a heck of a lot more helpful IME especially if you have a stack trace

lmm 7y ago

I find that requiring "nice" commit messages tends to mean digging through bigger diffs to find the breaking change. If you're fine with commit messages like "fix" or "derp", then people are more willing to make each tiny change a separate commit, and then a git bisect takes you right to the specific diff that caused the problem.

em-bee 7y ago
that is an interesting argument, but i don't quite buy it. the commit history is used for other things too, not just to find bugs using bisect. if that was the case we would not need any commit messages in the first place. how much effort does it take to explain the change in a sentence? if it is a small change then it also will be a small commit message. the commit message doesn't need to be nice, but it should be descriptive.
- lmm 7y ago
  > the commit history is used for other things too, not just to find bugs using bisect. Is it? People assume this, but I'm not convinced they use it for anything else in practice. > if that was the case we would not need any commit messages in the first place. I'd be interested in a VCS that followed through on this. Give PRs messages, maybe have some way to attach messages to tags, but permit individual commits to be anonymous. > how much effort does it take to explain the change in a sentence? if it is a small change then it also will be a small commit message. More effort than writing the change, often enough. In a high-quality codebase the code change should speak for itself. (And if it doesn't, you may well end up needing an explanatory comment in the code anyway).
  - em-bee 7y ago
    In a high-quality codebase the code change should speak for itself. (And if it doesn't, you may well end up needing an explanatory comment in the code anyway). that is indeed pretty much true. in that sense the commit message is just helping me to avoid needing to look at the diff. an outline of the commits. related to the PR, it would then be interesting to annotate groups of commits. a sequence of commits that make up a PR, but even without depending on the current PR mechanism (which at least in git is not stored anyways, so we need something to fill that gap) tags don't fit that, as they annotate a single commit, and we'd get to many tags that way. some other mechanism is needed to allow treating a series of commits as a unit.
pjc50 7y ago
Absolutely not! Submitting "derp" to code review is just disrespectful of the reviewer's time. There's a rationale for every change. The submitter knows it. The reviewer needs to know it. They can try reconstructing it from the diff, which is potentially error prone .. or you could just tell them. I'll accept "Fix ticket #1234", since that's moved the rationale elsewhere.