3 ms·

It's not a great git commit. 1) For all that text, the first line "Convert template to US-ASCII to fix error" - could be better. Maybe a couple of extra words

It's not a great git commit. 1) For all that text, the first line "Convert template to US-ASCII to fix error" - could be better. Maybe a couple of extra words to state what whitespace character caused the error, and what the error was. That comment plus the diff is all the context you need. 2) Honestly, everything else is kind of pointless. It doesn't hurt, but there's not a lot of value here. The author documented their journey in tracking this bug .. who cares?

GreenWatermelon 3y ago
People who like to learn and improve as programmers do care. In fact, the article explains the value of all that additional stuff which implies there are those who DO care. The article even provides a link to a search result showing multiple commits from people who learned from the fix. That commit message is a treasure trove of knowledge.
- macspoofing 3y ago
  Outside of the small caveat that his first line could be better (which is what all future engineers will read while scanning commit messages), like I said, at worst, it doesn't hurt. I like this level of detail, whether it is at the commit, PR, or ticket level. If one of my guys did this same write-up for this same problem, especially one of my junior guys, I would have patted them on the back and told them they did a great job - because you wouldn't want to discourage them from doing more of this kind of write-up in the future. But here, we can be a little bit more honest, and the truth is, that the problem he solved was trivial, so this kind of detail is overkill for that problem. Once find that the config file has unprintable non-ascii character, immediately you know most parsers would blow chunks on that - and there is only one fix - remove the problem character. So succinctly tell me the error you saw, tell me the character, and if you know tell me HOW it got in there (which is probably the most important detail that isn't in the write-up so this could be prevented in the future) - and that's enough because if in the future another engineer does a ticket/commit search for this error in our bug tracker, hopefully these details will show up immediately.

GreenWatermelon 3y ago

People who like to learn and improve as programmers do care. In fact, the article explains the value of all that additional stuff which implies there are those who DO care. The article even provides a link to a search result showing multiple commits from people who learned from the fix. That commit message is a treasure trove of knowledge.

macspoofing 3y ago
Outside of the small caveat that his first line could be better (which is what all future engineers will read while scanning commit messages), like I said, at worst, it doesn't hurt. I like this level of detail, whether it is at the commit, PR, or ticket level. If one of my guys did this same write-up for this same problem, especially one of my junior guys, I would have patted them on the back and told them they did a great job - because you wouldn't want to discourage them from doing more of this kind of write-up in the future. But here, we can be a little bit more honest, and the truth is, that the problem he solved was trivial, so this kind of detail is overkill for that problem. Once find that the config file has unprintable non-ascii character, immediately you know most parsers would blow chunks on that - and there is only one fix - remove the problem character. So succinctly tell me the error you saw, tell me the character, and if you know tell me HOW it got in there (which is probably the most important detail that isn't in the write-up so this could be prevented in the future) - and that's enough because if in the future another engineer does a ticket/commit search for this error in our bug tracker, hopefully these details will show up immediately.