4 ms·

That first line of the commit message is most important so that `git log` can address chesterton's fence. And IMHO in this case the committer whiffed. The key

by gumby 3y ago

That first line of the commit message is most important so that `git log` can address chesterton's fence. And IMHO in this case the committer whiffed. The key is not to put what you did in that first line, but why. Anyone interested in what can just look at the code, perhaps via a diff. So something like "nginx .conf files must be in us-ascii" Then "changed blahblah.erb to remove nonbreaking space character" Then the rest of the commit message which is quite good. Think of it as a news article: write in decreasing levels of importance and increasing levels of detail, assuming the reader could stop reading at any point.

nathan_phoenix 3y ago
> Think of it as a news article: write in decreasing levels of importance and increasing levels of detail, assuming the reader could stop reading at any point. Great quote and life advice, will definitely steal this! Thanks!
hatsix 3y ago
Nah, first line needs to be a summary of what you changed, so that you can find the offending commit in the first place. A news article doesn't explain WHY in the headline, it explains what. In this case, the OP's first line is spot on... if you're reading through git log, you can see that this commit likely didn't change anything functional about a test, and you should move on.
- tux1968 3y ago
  Hard disagree. There's little reason to search the text of commit messages to find out what changed. There are many git tools to find out which commits affected parts of the code you're interested in. Whereas, trying to find that in commit messages is really inefficient and relies on reading, rather than such automated tools. The purpose of the commit message is to help our fellow humans get a higher level understanding than is available from quickly scanning the code.
  - hermitdev 3y ago
    Totally agree with you. We already know what changed: it's the diff! We need to know why you're making the what. The message should address why the diff is necessary. Was it a bug fix? Ok, what's the bug you're fixing? What's the evidence that you think they diff addresses it? Is it a new feature? What's the requirement? I can already tell what you did by the diff, but I can't tell from the diff alone if it actually matches the requirement!
    - joshuamorton 3y ago
      This is true of the overall commit message, but we're talking about the first line. If I'm browsing git-log short or whatever, I don't have the diff, I have an ordered list of commit hashes and one line summaries, and I'm trying to decide which diffs I actually want to look more closely at.
  - myaccountonhn 3y ago
    I've never thought about it this way. I've always used it as a summary, so I can understand what has been done when browsing the history. It allows me to find changes that I want to cherry-pick or revert. OTOH I can see benefit of describing why a change was done as the summary, as then git blame on the line is a lot more effective.
joshuamorton 3y ago
But a commit message in an arbitrary project is not where you give someone a lesson about nginx rules. "nginx .conf files must be in us-ascii" is maybe a good bug or pull request title, but it may correspond to multiple commits that do different things, but it doesn't tell me what's happening. Is this converting a file to us-ascii, is this writing a tool to convert files to ASCII, is this updating documentation, is it creating a test, some combination? Leading with what, not why addresses that confusion.
palata 3y ago
> The key is not to put what you did in that first line, but why. Can't we just say that the key is to put something that makes sense for the first line, given that sometimes only the first line is printed? I don't really care if it says "The files must be in us-ascii" or "Changed the files to us-ascii"... both of them clearly tell me that the files were changed to us-ascii.
- gumby 3y ago
  The difference is Chesterton's fence: when you encounter something seemingly pointless you should learn why it was there before you consider removing or changing it.
  - palata 3y ago
    Ok, but when I read the first line of the commit, I am usually not considering removing or changing it. When I consider removing or changing the content of a commit, the least I can do is read the full commit description.

by gumby 3y ago

nathan_phoenix 3y ago

> Think of it as a news article: write in decreasing levels of importance and increasing levels of detail, assuming the reader could stop reading at any point. Great quote and life advice, will definitely steal this! Thanks!

hatsix 3y ago

Nah, first line needs to be a summary of what you changed, so that you can find the offending commit in the first place. A news article doesn't explain WHY in the headline, it explains what. In this case, the OP's first line is spot on... if you're reading through git log, you can see that this commit likely didn't change anything functional about a test, and you should move on.

tux1968 3y ago
Hard disagree. There's little reason to search the text of commit messages to find out what changed. There are many git tools to find out which commits affected parts of the code you're interested in. Whereas, trying to find that in commit messages is really inefficient and relies on reading, rather than such automated tools. The purpose of the commit message is to help our fellow humans get a higher level understanding than is available from quickly scanning the code.
- hermitdev 3y ago
  Totally agree with you. We already know what changed: it's the diff! We need to know why you're making the what. The message should address why the diff is necessary. Was it a bug fix? Ok, what's the bug you're fixing? What's the evidence that you think they diff addresses it? Is it a new feature? What's the requirement? I can already tell what you did by the diff, but I can't tell from the diff alone if it actually matches the requirement!
  - joshuamorton 3y ago
    This is true of the overall commit message, but we're talking about the first line. If I'm browsing git-log short or whatever, I don't have the diff, I have an ordered list of commit hashes and one line summaries, and I'm trying to decide which diffs I actually want to look more closely at.
- myaccountonhn 3y ago
  I've never thought about it this way. I've always used it as a summary, so I can understand what has been done when browsing the history. It allows me to find changes that I want to cherry-pick or revert. OTOH I can see benefit of describing why a change was done as the summary, as then git blame on the line is a lot more effective.

joshuamorton 3y ago

But a commit message in an arbitrary project is not where you give someone a lesson about nginx rules. "nginx .conf files must be in us-ascii" is maybe a good bug or pull request title, but it may correspond to multiple commits that do different things, but it doesn't tell me what's happening. Is this converting a file to us-ascii, is this writing a tool to convert files to ASCII, is this updating documentation, is it creating a test, some combination? Leading with what, not why addresses that confusion.

palata 3y ago

> The key is not to put what you did in that first line, but why. Can't we just say that the key is to put something that makes sense for the first line, given that sometimes only the first line is printed? I don't really care if it says "The files must be in us-ascii" or "Changed the files to us-ascii"... both of them clearly tell me that the files were changed to us-ascii.

gumby 3y ago
The difference is Chesterton's fence: when you encounter something seemingly pointless you should learn why it was there before you consider removing or changing it.
- palata 3y ago
  Ok, but when I read the first line of the commit, I am usually not considering removing or changing it. When I consider removing or changing the content of a commit, the least I can do is read the full commit description.