4 ms·

It's not only about the fact that the commit message for a one char change is about a page long. It's about that all the information in that page long commit me

by neo2006 7y ago

It's not only about the fact that the commit message for a one char change is about a page long. It's about that all the information in that page long commit message is a useful information

deleted 7y ago
[deleted]
BoorishBears 7y ago
Strongly disagree. There is so much superfluous cruft in the message. Listing the error, and the fix, would give exactly as much context for the next person to run into this issue. If your goal to explain the process to find similar cases, just a couple more lines would have done just as well: - Fixes case where `bundle exec rake` would fail with error message: ArgumentError: invalid byte sequence in US-ASCII This is caused by the presence of non-ASCII characters in files. The following command was used to find files with non-ASCII characters: `find modules -type f -exec file --mime {} \+ | grep utf` Running `iconv -f UTF8 -t US-ASCII` on listed files will show the exact location of offending characters. - No long winded exposition, no extremely case specific program output (including current machine's name...) I’m not saying this is the worst commit message ever, and I’d appreciate the intention if I came across it, but if you’re caring enough to give this much context, you can save both yourself, and the next person to look for your message, some cognitive load by sticking to what’s needed. - And if you’re wondering how to decide “what is needed”, it varies, but I think a good rule of thumb is: ask yourself how one would find this commit message What would someone grep for in git's history if they came across this? And if they found it, what information answers their query? They’re likely to search the command that is failing, and the error. The answer to that query is, what causes the command to error out, and how to find cases of that cause. They’re not going to search for the program output of find, or iconv, not going to search for the exact file you were modifying when this happened, or the fixes you tried that didn’t work.
- skrebbel 7y ago
  I disagree. I mean, you're right, but I don't think that's time well spent. This is a commit message, not a blog post. Writing concisely is hard and time consuming. This was probably written in stream-of-consciousness fashion which strikes a nice balance between time invested and possible future usefulness (if any). I mean, the commit might be useful in the future, but there's also a reasonable chance that nobody except the reviewer of the PR is ever going to read that commit message. (If the OP hadn't blogged about it)
  - BoorishBears 7y ago
    How is writing concisely more time consuming than this long winded stream of consciousness with multiple quoted command outputs and explanations of non-fixes? If I come across an error and it takes two commands to fix it, my immediate intuition is a commit message with... the error and the two commands. And that’s extremely quick to write... It’s definitely not “let me write a detailed account of the last hour of my life”... that immediately feels like it will take much longer Also to be clear, the rule of thumb I mention is not about “what should you think about, then write down” It’s a filter on what you were already about to invest effort in writing down. If you feel like an even shorter message is good enough, that’s great. Just realize sometimes less is more...
    - JoshTriplett 7y ago
      It's the exact opposite of "If it was hard to write, it should be hard to understand". This is "This was hard to debug, so let me make it easy to understand and give you (or future me) the hard-won information I just discovered so that you don't have to go through what I did". If the information took you a great deal of effort to get, that suggests it may be valuable to share. That may not be the right time to attempt to cut out some of that information for brevity, especially if you don't know what the future reader of the message might need to know.
      - BoorishBears 7y ago
        What information in the concise version I gave is missing, that causes you to go through additional effort? I think you edited this in after my reply: > If the information took you a great deal of effort to get, that suggests it may be valuable to share. I think this is the core of where we disagree. I often spend insane amounts of time debugging something, only to find the solution was quite simple and unrelated to what I tried. Often the amount of time you spent debugging is because the search space for your solution was unbounded, not because each step you took was particularly relevant to the actual solution. To me a commit message should be able hopefully narrowing that search space, not documenting the original unbounded one.
- neo2006 7y ago
  I see your point, but as a person that get bored easily when I read, I like how it give context and narrate a story instead of writing only the technical facts. Even if it's lengthy, it's a commit message I will finish reading.

It's not only about the fact that the commit message for a one char change is about a page long. It's about that all the information in that page long commit message is a useful information

deleted 7y ago

[deleted]

BoorishBears 7y ago

Strongly disagree. There is so much superfluous cruft in the message. Listing the error, and the fix, would give exactly as much context for the next person to run into this issue. If your goal to explain the process to find similar cases, just a couple more lines would have done just as well: - Fixes case where `bundle exec rake` would fail with error message: ArgumentError: invalid byte sequence in US-ASCII This is caused by the presence of non-ASCII characters in files. The following command was used to find files with non-ASCII characters: `find modules -type f -exec file --mime {} \+ | grep utf` Running `iconv -f UTF8 -t US-ASCII` on listed files will show the exact location of offending characters. - No long winded exposition, no extremely case specific program output (including current machine's name...) I’m not saying this is the worst commit message ever, and I’d appreciate the intention if I came across it, but if you’re caring enough to give this much context, you can save both yourself, and the next person to look for your message, some cognitive load by sticking to what’s needed. - And if you’re wondering how to decide “what is needed”, it varies, but I think a good rule of thumb is: ask yourself how one would find this commit message What would someone grep for in git's history if they came across this? And if they found it, what information answers their query? They’re likely to search the command that is failing, and the error. The answer to that query is, what causes the command to error out, and how to find cases of that cause. They’re not going to search for the program output of find, or iconv, not going to search for the exact file you were modifying when this happened, or the fixes you tried that didn’t work.

skrebbel 7y ago
I disagree. I mean, you're right, but I don't think that's time well spent. This is a commit message, not a blog post. Writing concisely is hard and time consuming. This was probably written in stream-of-consciousness fashion which strikes a nice balance between time invested and possible future usefulness (if any). I mean, the commit might be useful in the future, but there's also a reasonable chance that nobody except the reviewer of the PR is ever going to read that commit message. (If the OP hadn't blogged about it)
- BoorishBears 7y ago
  How is writing concisely more time consuming than this long winded stream of consciousness with multiple quoted command outputs and explanations of non-fixes? If I come across an error and it takes two commands to fix it, my immediate intuition is a commit message with... the error and the two commands. And that’s extremely quick to write... It’s definitely not “let me write a detailed account of the last hour of my life”... that immediately feels like it will take much longer Also to be clear, the rule of thumb I mention is not about “what should you think about, then write down” It’s a filter on what you were already about to invest effort in writing down. If you feel like an even shorter message is good enough, that’s great. Just realize sometimes less is more...
  - JoshTriplett 7y ago
    It's the exact opposite of "If it was hard to write, it should be hard to understand". This is "This was hard to debug, so let me make it easy to understand and give you (or future me) the hard-won information I just discovered so that you don't have to go through what I did". If the information took you a great deal of effort to get, that suggests it may be valuable to share. That may not be the right time to attempt to cut out some of that information for brevity, especially if you don't know what the future reader of the message might need to know.
    - BoorishBears 7y ago
      What information in the concise version I gave is missing, that causes you to go through additional effort? I think you edited this in after my reply: > If the information took you a great deal of effort to get, that suggests it may be valuable to share. I think this is the core of where we disagree. I often spend insane amounts of time debugging something, only to find the solution was quite simple and unrelated to what I tried. Often the amount of time you spent debugging is because the search space for your solution was unbounded, not because each step you took was particularly relevant to the actual solution. To me a commit message should be able hopefully narrowing that search space, not documenting the original unbounded one.
neo2006 7y ago
I see your point, but as a person that get bored easily when I read, I like how it give context and narrate a story instead of writing only the technical facts. Even if it's lengthy, it's a commit message I will finish reading.