41–50 of 406 posts
But I disagree about the format. I prefer commit messages like:
JIRA-123 one-line 80-char-at-most description
Long description if needed (but preferably keep it in JIRA).I had a terrible time when someone used "smart quotes" (beautified Office quotation marks) in a configuration file. I believe this was only possible because they copied it from Outlook.
>smart quotes I never understood why a "stylistic" choice requires separate characters. If we don't need a serif and non-serif version of every character and instead leave it to the software, why can't we do the same with the "smart" quotes?
I don’t think it’s a purely stylistic choice, there is actually semantics to it:
“ opening quotation mark, i.e.: starts the quote
” closing quotation mark, i.e.: ends the quote
I have felt that pride in writing a great commit message, but I am less sure of the value to others. I don’t think most people search commit messages when they encounter an unusual error message, or when adding a new feature, or really almost ever. It’s a bit sad, but I have a growing suspicion that beautiful commit messages are a bit of vanity by the programmer. The person primarily impressed is often the author; ot…
I've been bitten by this many times - I change obvious bug, I'm about to commit the changes, I see the previous commit which introduced the "bug" on purpose and the attached JIRA task has perfectly good explanation for why my obvious change would have reintroduced some bug from 2 years ago :)
The first line always mentions the subsystem affected by the change, followed by a one-line imperative-mood summary of the change. Subsequently, three questions are answered in as much detail as possible:
1. What is the current behaviour? 2. What led to this change? 3. What is the new behaviour after applying this change?
Example:
"Currently, code does X. When running test case T, unexpected behaviour U was observed. This is because of reason R. Fix this by doing F."
Earlier quoted context omitted.
> I have felt that pride in writing a great commit message, but I am less sure of the value to others. I don’t think most people search commit messages when they encounter an unusual error message, or when adding a new feature, or really almost ever. They have value even if the only person who will ever look at them is you - and I will say that when bisecting an issue, the commit message of the commit I finally find…
In some orgs, people never run a bisect. Not once a year. They go as far as squashing out swaths of history into big un-reviewable blobs. Once code has been merged, they never look inside a past commit again. In spite of isolated (desperate) demands for rigor, it works fine.
You want to know why a change was made, or who so that they can explain it. You land on a blob of a diff, with no meaningful commit message (any commit message was squashed to /dev/null to be replaced with the MR title and description). And then off you go to the corresponding github/gitlab/whatever MR only to find a wall of "hmmmm" "why no work?" "try something" etc commits.
I think the disadvantage with this style of documentation is you can't really alter the commit message after it's written. (I mean you could obviously with "rebase" but are you really going to alter something written one year ago, already merged to "main", and cause a bunch of pain with everyone's feature branch etc.?) Compare that with documentation stored in a .md file, or even a Wiki or even Confluence. My colleag…
I really think git made a mistake in conflating the immutable log of what was changed with the (ideally mutable) story of what got merged in. So you see people arguing over squashing commits vs rebasing vs merging. Squashing commits makes the history of commits a better story of features being added. Merging preserves the immutable log of the actual changes made to the code, and rebasing sort of does a bit of both. B…
Something like:
syn match unicodeWhitespace /[list of unicode whitespace]/
hi def link unicodeWhitespace ErrorI have felt that pride in writing a great commit message, but I am less sure of the value to others. I don’t think most people search commit messages when they encounter an unusual error message, or when adding a new feature, or really almost ever. It’s a bit sad, but I have a growing suspicion that beautiful commit messages are a bit of vanity by the programmer. The person primarily impressed is often the author; ot…
where great commit messages like the one in the blog post make perfect sense are pull requests. If the commit message explains the whole thought process that the author had while working on it, it saves so much time on pull request review.
I think the disadvantage with this style of documentation is you can't really alter the commit message after it's written. (I mean you could obviously with "rebase" but are you really going to alter something written one year ago, already merged to "main", and cause a bunch of pain with everyone's feature branch etc.?) Compare that with documentation stored in a .md file, or even a Wiki or even Confluence. My colleag…
That is not a disadvantage. The commit is a historical record, if I come back to that commit 3 years later I want to know its purpose in the context it was in, I don’t want a whitewashed history.
> Compare that with documentation stored in a .md file, or even a Wiki or even Confluence. My colleague can write something and if I see a way to improve it I can go ahead and do that, and other colleagues can improve on what I've written.
That’s like comparing a bicycle and a goose.
> But I also myself find it tempting to describing the design of a particular component when I commit that component, and that's something I now avoid.
That’s a shame. Knowing the considerations (or lack thereof) and tradeoffs at time of creation are often useful to understand defects, either in the original, or in evolutions, or in changes of use case.
> Will the commit documentation just describe the differences?
Yeees?
> Then in order for a new team member to find out how the system works by reading the documentation they've got to read multiple commit messages and "merge" them in their head.
No, for that you maintain a separate “current” documentation, which does not need to cover implementation tradeoffs, or that the original was written under time crunch, or whatever.
Earlier quoted context omitted.
>smart quotes I never understood why a "stylistic" choice requires separate characters. If we don't need a serif and non-serif version of every character and instead leave it to the software, why can't we do the same with the "smart" quotes?
Typographic quotes are left- and right-handed, vs. the ASCII double quote which is just a single character: “quoted” "quoted" Who in the blazing highs of techno-utopianism fervor thought it was a good idea to automatically translate the latter to the former we'll never know.
Sadly the new official french azerty keyboard has dedicated keys for both opening and closing quotes, and the good ol' simple quote tucked away behind modifier keys. As a dev I hate it. (arguably I should not even use azerty for development but that's another issue)