4 ms·
I agree with you that the little innocuous things often need a longer explanation, but the linked commit message is way too long IMO. It either wastes the reade
by unregistereddev 3y ago
I agree with you that the little innocuous things often need a longer explanation, but the linked commit message is way too long IMO. It either wastes the readers' time, or it causes the readers' eyes to gloss over at the wall of text. You don't need to document your entire journey in order to document your findings and explain why.
> This was a non-ascii whitespace character that caused `ArgumentError: invalid byte sequence in US-ASCII` when running `bundle exec rake`
^ should be sufficient. It includes enough keywords to come up in a search if someone has a similar problem in the future, it contains the root cause of the problem, and it is short enough that people are unlikely to gloss over it.
- mbork_pl 3y agoThe article explains why all the rest is, maybe not needed, but good to have.
- OJFord 3y agoYes, it's not my preferred style either, but it's much better than 'fixes error' type thing, subject line only, that's so common. I like the form: Fix ArgumentError 'invalid byte sequence' Non-ASCII whitespace characters cause [...]. This was apparent in [...] because [...]. This commit fixes the issue by removing the offending character; so the file is now solely ASCII characters. Or that sort of thing. Subject tells me why, body tells me what the problem was and how it was fixed. (Who, when, where are already in the commit metadata! The diff shows a very literal 'what' too, the what/how in the body should offer context and explanation as required.)