3 ms·

I thought it was very meta amusing that the author was trying to tell users how to write commit messages when the number one rule of commit messages in my book

by icefox 12y ago

I thought it was very meta amusing that the author was trying to tell users how to write commit messages when the number one rule of commit messages in my book is explaining WHY the commit exists. Why does this patch change this or do that. So it was amusing when he lists commit rules without explaining why they are rules. But I was saddened when I got to the end and missing from the list is 'explain why'. Why did you 'Add feature...'? Why did you 'Move cursor to...'? I did stuff // Increment i by 1 Why I did stuff // Increment i by 1 to not have a off by 1 bug

Morgawr 12y ago
I see three different types of commits in my codebase, usually. * The big fix: This is the commit which usually is too complex to be explained in a 72-characters message. Usually it refers to an issue number on the project's issue tracker, which in my case is Github. * The medium fix: This is a commit whose "why" fits properly into 72 characters, i.e. "Add classes to validate user input only on Friday". * The small/obvious fix: This is a very small commit, usually fixes obvious issues like CI builds, misspellings in doc files, missing semi-colons, etc etc. In the last case, I find it appropriate to write the "how" rather than the "why" in the commit message, since the why is already obvious. i.e. "Add missing comma on object identifier".
davexunit 12y ago
>the number one rule of commit messages in my book is explaining WHY the commit exists The commit message should say what changed, not why. Comments are for explaining why the code does what it does. Good commit log: http://git.savannah.gnu.org/cgit/guix.git/commit/?id=fb519bd8313e192d6eca2e51f9f33c87e5ee883e http://git.savannah.gnu.org/cgit/guix.git/commit/?id=fb519bd...
- qznc 12y ago
  Comments tell why the code does what it does. Commit messages tell why the code does something different than before. Example comment: i++; // because server starts counting at 0 (not 1) Example commit: Our customer switched to bar (from foo), which starts counting at 0 instead
- pjc50 12y ago
  The diff shows you what changed. The commit message is a comment on the diff and absolutely should say what it's for. This enables you to easily compile release notes, for example.
  - davexunit 12y ago
    Yes, it should say what it's for, but it shouldn't need to explain itself any further. Sorry if I didn't make that clear. For example, if someone refactored something, the commit log can simply say "Factorize foo", it need not explain why they were refactoring in the first place.
- nirvdrum 12y ago
  That works as long as you're adding code. But what about when you're deleting code? I absolutely want to know why you've removed something.
xorcist 12y ago
The "why" can live in the bug tracker, as a feature or fix may have several commits attributed to it. For larger centralized projects, I have found a requirement on issue numbers in commit messages to work well. It makes a whole lot of management issues easier.
- icefox 12y ago
  If issue numbers are the only requirement, is it okay if every commit only includes an issue number and no text at all? If not, why not? If they say something should it be the exact same thing as the issue title?
  - xorcist 12y ago
    IMHO, no. You should be able to read a commit log and understand what has been done. But if the issue titles are good enough they could absolutely be used as commit messages. Many issues leads to multiple commits however, so what you want for message is a description of the individual commit.

by icefox 12y ago

Morgawr 12y ago

I see three different types of commits in my codebase, usually. * The big fix: This is the commit which usually is too complex to be explained in a 72-characters message. Usually it refers to an issue number on the project's issue tracker, which in my case is Github. * The medium fix: This is a commit whose "why" fits properly into 72 characters, i.e. "Add classes to validate user input only on Friday". * The small/obvious fix: This is a very small commit, usually fixes obvious issues like CI builds, misspellings in doc files, missing semi-colons, etc etc. In the last case, I find it appropriate to write the "how" rather than the "why" in the commit message, since the why is already obvious. i.e. "Add missing comma on object identifier".

davexunit 12y ago

>the number one rule of commit messages in my book is explaining WHY the commit exists The commit message should say what changed, not why. Comments are for explaining why the code does what it does. Good commit log: http://git.savannah.gnu.org/cgit/guix.git/commit/?id=fb519bd8313e192d6eca2e51f9f33c87e5ee883e http://git.savannah.gnu.org/cgit/guix.git/commit/?id=fb519bd...

qznc 12y ago
Comments tell why the code does what it does. Commit messages tell why the code does something different than before. Example comment: i++; // because server starts counting at 0 (not 1) Example commit: Our customer switched to bar (from foo), which starts counting at 0 instead
pjc50 12y ago
The diff shows you what changed. The commit message is a comment on the diff and absolutely should say what it's for. This enables you to easily compile release notes, for example.
- davexunit 12y ago
  Yes, it should say what it's for, but it shouldn't need to explain itself any further. Sorry if I didn't make that clear. For example, if someone refactored something, the commit log can simply say "Factorize foo", it need not explain why they were refactoring in the first place.
nirvdrum 12y ago
That works as long as you're adding code. But what about when you're deleting code? I absolutely want to know why you've removed something.

xorcist 12y ago

The "why" can live in the bug tracker, as a feature or fix may have several commits attributed to it. For larger centralized projects, I have found a requirement on issue numbers in commit messages to work well. It makes a whole lot of management issues easier.

icefox 12y ago
If issue numbers are the only requirement, is it okay if every commit only includes an issue number and no text at all? If not, why not? If they say something should it be the exact same thing as the issue title?
- xorcist 12y ago
  IMHO, no. You should be able to read a commit log and understand what has been done. But if the issue titles are good enough they could absolutely be used as commit messages. Many issues leads to multiple commits however, so what you want for message is a description of the individual commit.