Reject commit message suggestions
When working on large software projects, commit messages that follow
the format suggested by the author rarely provide additional value.
Having commits prefixed by "chore:" or "docs(ui):" aren't that useful.
Instead, some of those 50 characters can be used for more descriptive
titles. Commit messages are often the best and only context available
when bisecting a bug, so bullet points only really make sense when
making a list. Prose works just fine.
Writing styles vary across contributors but it's much more useful to
get *anything* from someone in their preferred format than nothing at
all because they are frustrated with rules. Some committers do have a
special "committer voice" that they use when describing complex changes
in a commit message. For example, the text here is slightly abridged
and focuses less on the first person than what is typically expected.
This evolves naturally from writing these.
Finally, commit comments definitely should have jokes in them. This is
actually more critical than wrapping them at 72 characters.
The author is working in an environment where, left to their own device and allowed free form messages, programmers write the three word sentences shown in the blog post.
This is the downside of the variation in style across contributors. It works if people want to build something, and not just do the minimum. Open source projects frequently have no such limitations.
But I am sad to report that some people appear to need the structure.
Address structural issue with code contributions
In some cases, it's possible to end up with commit messages that carry
very little value. Unfortunately, while the minimum is clearly
insufficient, it is possible to "expand" the minimum into a specific
format without substantially improving the quality of the commit
message. For example, a substantial refactor can easily just be
described as a list of the changes that it included, rather than a
rationale for why it was done (which is not readily apparent from the
change itself).
In the long run, problems involving people can be improved by process,
but cannot wholly be solved by them. Pernicious failures need to be
acted upon directly. Demonstrating the value of good commit messages is
often a better driver of improvements than a template that is a chore
to fill out.
In my experience, people write overly short commit messages when they're writing too many commit messages. The solution is usually not to teach people to write better commit messages (although that's also good), but to teach them how to group and bundle commits together to create a meaningful standalone patch.
One of the easiest ways to start there is to adopt PR-based review systems, where any number of commits can get pushed to a git repository and then reviewed as a single block. This is fairly inflexible, but it is very simple to get started with (no need to learn any special rebasing commands, just add, commit, add, commit, push). Most git forges allow you to do squash merges, so everything in the PR will become a single commit, usually with the PR description as a commit message. Then you can refine the commit and commit message during the review process.
There are better tools out there, but in my experience, this is the quickest way to get started for most teams, especially as you're probably already using a forge that allows you to do all of this already.
Also, reconsider column-based hard-wrapping entirely,
and consider wrapping mostly on punctuation,
or other reasonable opportunities when it gets a bit long
and you don’t really want to insert punctuation.
This is not without its drawbacks and limitations—
most software when rewrapping won’t cope with trailing em dashes,
and you’ll end up with extraneous spaces when the lines are merged,
even though this is *always* how wrapping has worked around dashes.
Over time, this will definitely influence your writing style.
Your sense of æsthetics will push you to reword sentences,
because otherwise the edge is too ragged for your liking,
and at some point you’ll see a pattern in a paragraph,
and feel an uncontrollable urge to continue it,
and you’ll waste a bunch of time tweaking,
and maybe no one will appreciate it.
But you’ll appreciate it.
It’ll be fun.
Mostly.
But seriously, you *will* become more aware of things like clause length,
and your writing will probably improve.
And after writing verbosely for a long time,
you’ll focus on concision,
and that’ll be another challenge.
And it’ll be fun too.
Mostly.
Then probably someone will take over your pet docs project,
and mandate an autoformatter that rewraps it to 59 columns.
Stubbornly, in the quiet of your mind, you’ll make it work.
It’s a greater challenge, but you won’t lack determination.
Style guides come, and style guides go; when this one goes,
your lines can remain the same, needing no fixing, perfect.
—⁂—
And really, just look at how the last paragraph of the parent comment looks,
before and after:
Finally, commit comments definitely should have jokes in them. This is
actually more critical than wrapping them at 72 characters.
—⁂—
Finally, commit comments definitely should have jokes in them.
This is actually more critical than wrapping them at 72 characters.
Much more beautiful, is it not?
top: attempt once again to allow help text translation
Back when our release 4.0.1 was being readied, sources
were sent to the TP (Translation Project). However one
person named Benno Schulenberg refused to release them
for translation. His stated reason was the top command
line help text which then finally included long forms.
He demanded that the help text be broken into separate
strings instead of a single large string. But, all the
top text (some much more complex) has just one string.
So that stated reason was, at the least, inconsistent.
[ I suspect the real reason was that Mr. Schulenberg ]
[ thought that the carefully right-justified English ]
[ wording would also be required of translations too ]
The bottom line was that Benno took it upon himself to
change the TP motto from "you code, we translate" into
"first we tell you how to code and then we translate".
Rather than bend a knee to that despot, I disabled the
text entirely, admittedly denying users a translation.
Now, with this commit we enable translatable help text
but with a hint included to ignore the justified text.
Reference)s):
. Oct, 2022 - finalized translation exclusion
commit ab05a3785f29cc4b754e17c53bfb3d8ba054563e
Signed-off-by: Jim Warner <james.warner@comcast.net>
Reducing the human-readability of the most human-presented part of the commit, to make it easier for the can-do-billions-of-operations-a-second machine, seems backwards.
