I find this way WAY harder to read/scan, and very much prefer Google's standard: https://google.github.io/eng-practices/review/developer/cl-d...
I find this way WAY harder to read/scan, and very much prefer Google's standard: https://google.github.io/eng-practices/review/developer/cl-d...
What's your evidence or supporting research?
> things are easier to scan if the more important part is first
You skipped the step where "most important" is defined.
> "Specifier can be configured when constructing a store"
This is just about the worst type of commit message, in my opinion, only marginally better than an empty commit message.
Ok. Specifier can be configured when constructing a store. Is it supposed to? Is it the state before or after the commit? Is this just context, and maybe this commit changes documentation to reflect that reality?
You even say that reading a bunch of them is uncomfortable.
> It's not about the self. It's about the code.
Actually, it's about the change. When something broke, what changed. When a new release comes out, what changed.
Some people prefer the past form "Added feature X" instead of "Add feature X". On that I just say "be consistent".
Also note that your first batch of examples are inconsistent. "Whitespaces", "We don't use `::` to denote class methods", "Avoid __method__", past/present verb form, etc. The difference isn't just the form, but whether commits actually follow any style at all.
> I eventually recognized the benefit of scannability
Scannability is hugely important. People who disagree with your style of commit message don't disagree with you on that.
> For example, "Widget tests" is preferred over "Widget tests are added".
What about the widget tests?
> When describing a version increase, be explicit about both the old and the new version. E.g., "Package version is increased from 1.1.1 to 1.2.0"
Are version numbers ever decreased?
(1.1.2 can be released after 1.2.0, yes, but that's not a decrease even if something was backported)
We didn't need it. It was based on a-priori knowledge. For example, we don't write email subjects like: "Convey information about new release", or "Ask question about time off". We know from how the human brain processes content (eye tracking studies) that they scan in an F-shaped pattern. This puts emphasis on the content on the left. If the left side has no differentiation, this is, de facto, harder to scan.
You don't have to agree with me. As my colleague said, there are other, even more subtle things we are trying to convey and reinforce: https://news.ycombinator.com/item?id=38836919
> You skipped the step where "most important" is defined.
No, we literally do this every time we write a commit message. This is a usability issue. What is the most important thing to the reader?
> Ok. Specifier can be configured when constructing a store. Is it supposed to? Is it the state before or after the commit? Is this just context, and maybe this commit changes documentation to reflect that reality?
And yet, when all of your commit messages are in a consistent voice and mood, there is no ambiguity. Also, all of your questions are answerable from a self-evident perspective -- if you can rely on your teammates to care about your ability to understand what they write. Of course it's supposed to, otherwise why would I commit it? Of course it's the state after the commit, why would I talk about what was (How many newspaper articles about a celebrity's death have a headline saying they are sick?)? Of course it's not about documentation, it would say it was if it was. In short, you can make up as many holes as you want to poke through.
> You even say that reading a bunch of them is uncomfortable.
I said at first. See: familiarity bias
> What about the widget tests?
This is convention that one could argue requires memorization. I don't actually think it does, however, because of how we as humans interpret subjects/headlines.
> Are version numbers ever decreased?
They have been, and I hope it's self-evident how that commit message would be constructed on our project.
In any case, I'm not here to quibble about commit message formats. I documented ours and gave supporting rationale which is based on UX knowledge (and research, at the very least, see eye tracking studies). If you think that "Fix", "Fix", "Add", "Change", are the most important part of the commit message, then I'm not really going to be able to or even bother trying to convince you otherwise.
Well, you may hold these truths to be self-evident, but that's hardly an argument. And since you say "It's likely what your team uses, as it is the commit message style that is typically recommended as a "best practice" you acknowledge that you hold a minority opinion.
"What I'm saying is self-evidently true" is unlikely to sway anyone.
And I find it dishonest to phrase that as "The psychology portion isn't subjective".
From your colleague:
> The reason that the "subject-first" approach is used is to get contributors to talk specifically to the impacts made to the software itself, rather than talk about themselves and their labors.
I don't recognize that description at all about the majority opinion. Yes, some people write terrible commit messages, but that's not the best practice you seek to upend.
> Of course it's the state after the commit, why would I talk about what was
You'd be surprised. It's more common in bug reports, but I've seen this in commit messages too.
>> Are version numbers ever decreased? > They have been,
Oh, really? Do you have an example?
> In any case, I'm not here to quibble about commit message formats.
Thanks for clarifying that you base this policy on nothing but your subjective opinion, that there is no research to support it, and that everyone else is doing it wrong, because your subjective is clearly objective.
Nothing wrong with that. I do have a problem with you misrepresenting this as objectively better, with a handwavy "scan in F shape". Don't say it's based on research when it's just your "common sense". That's unprofessional.
An opinion being minority has no reflection on whether or not it is correct. See hand washing in the medical profession before it was understood, or batch sizes in the automobile industry before Toyota ate the west's lunch.
> And I find it dishonest to phrase that as "The psychology portion isn't subjective".
You can find it dishonest if you wish, but I'm trying to point to a body of knowledge I can't adequately convey in an article or a hackernews comment. I'm not trying to pull one over on you, I promise. As I said in another response, this is a design decision. Most design decisions are based on first principles, a-priori knowledge, expertise, a wide range of studies and observations over time, etc. If a person can't write down (convincingly) all of the tacit knowledge required to make the same decision, they are not being dishonest.
I'll say it this way: We made this decision based on objective factors. I do not expect everyone to be able to see our decision or our reasons in the same objective light and I'm not going to try to convince someone that doesn't. But telling me it's purely subjective is gaslighting, and impugning my integrity over it is just rude.
> You'd be surprised.
No, I wouldn't. I would be surprised to see it on our team, or any other well-disciplined team. This article is a tiny (and frankly pedestrian) part of our overall development process. I'm sure you'd disagree with just about everything else that we do as well, and that's OK as well.
> Oh, really? Do you have an example?
Sure:
mail package version is decreased from 2.8.0 to 2.7.1
This happened when we were forced to pin to an older version of the mail gem because of a regression in 2.8.0.
Note that the scenario you described: "(1.1.2 can be released after 1.2.0, yes, but that's not a decrease even if something was backported)" isn't relevant to our practice. We don't maintain multiple major/minor versions at one time of any of our packages. If we did, they would be on separate branches as the version number can only exist in one place (the gemspec) and the same exact rules would apply. That is, it wouldn't be a version decrease, it would be an increase from 1.1.1 to 1.1.2 on the 1.1 branch.
I entirely agree. But if you find yourself in the minority, then I encourage you to objectively consider what's more likely: Are you right, or are most other people right? Or maybe there is no right and wrong (aside from being consistent)?
Sometimes the minority is right. But usually that's not the case.
> See hand washing in the medical profession before it was understood.
Ooookayy. I would not compare any technical decision in this space to that. A bit grandiose. More traditionally one says "10k flies can't be wrong: poop must taste great!".
> If a person can't write down (convincingly) all of the tacit knowledge required to make the same decision, they are not being dishonest.
I agree. As long as they don't claim otherwise. I'm sure you're an expert, with lots of experience. Experience that creates a good judgement, and good intuition. But that also describes the majority of the experts, who, turns out, disagree with you.
>> You'd be surprised. > No, I wouldn't.
Then... you disagree with the "of course", you said.
> mail package version is decreased from 2.8.0 to 2.7.1
What does that mean? A dependency version decrease? If this is a commit on the mail package itself, then what does it mean?
I'm going to assume that's a dependency version change.
"10k flies can't be wrong" is one thing, but "the majority expert opinion in my field is wrong"... is almost always wrong.
Most theories are wrong, even by experts. It's not even embarrassing to be wrong.
But to defend your policy on objective grounds, is like asserting Ruby should be used for all programming. It's Not Even Wrong. https://en.wikipedia.org/wiki/Not_even_wrong
https://www.nngroup.com/articles/first-2-words-a-signal-for-...
https://www.nngroup.com/articles/text-scanning-patterns-eyet...
https://www.nngroup.com/articles/list-entries/
Commit summaries are typically viewed as lists (though not always, and in that case you often have more context, e.g., the rest of the message and the diff)
We optimize them as we would list entries in any other thing we design for human consumption.
Btw, we didn't refer to these specific articles when we made our decision, I found them just now.
I updated my article with links to these. Thanks again for the discussion.
One has to be able to understand an analogy for the point the person is trying to make -- it's not an equivalence. Obviously most software issues don't rise to the level of life or death.
That said, let's try a few others:
- Waterfall
- DCOM
- CORBA
- Web Services
- Microservices (as implemented by web developers -- per-entity web api to web api to web api cascading failure)
- Monorepos (not globally, with sufficient support these can work)
- Devs shouldn't write tests
- Fat Model, Skinny Controller
- Write tests. Not too many. Mostly integration.
- Single Page Apps for all
- SCRUM
- Story points
Most, if not all of those were embraced by "most experts", but are now demonstrated problematic or at least are knowably wrong from fundamental design principles. Note that statistically speaking, "most experts" are, at best, early majority. There aren't very many in the Innovators and Early Adopters, and crossing that chasm is rare, and hard.
We have a history in our community of intransigence, repeating mistakes, and expert beginners being the most outspoken portion of our community. They are the ones that have the most to gain by blogging and self-promotion and there are significantly more of them than people who may have different things to say for good reason. Note that right now, I am speaking generally, not debating a commit message approach.
> Then... you disagree with the "of course", you said.
No, the "of course" was: of course no one I work with would make that mistake (more than once). It would be an extremely beginner mistake, and we would have failed as coaches on our team to not pair with a person long enough to help them understand how to write proper commit messages.
> I'm going to assume that's a dependency version change.
Yes, it's a pinned version for that dependency. You don't have any context on that particular commit, so it's not surprising that it's ambiguous.
> Most theories are wrong, even by experts. It's not even embarrassing to be wrong.
Indeed! I have been wrong many times in my career. Hell, I invented the "auto-mocking container" which, in hind sight was so stupid (and btw, my colleague you referenced warned me about it at the time -- he's always been a few steps ahead) that I never should have popularized it. Thankfully, it fell into the past along with IoC containers (for the most part).
I have plenty of other stories about being wrong as well, and as I've said elsewhere, if we find a better way to write commit messages we will do that. For now, from our analysis, the way we do it is best for us -- observably (I'll say that, rather than objectively, though I do believe we were as objective as possible in our analysis).
Thanks for the discussion.
It's called a change list even though it's a single commit because Perforce tracks changes per file, so if you modify multiple files in a single commit, you are introducing a list of changes in their model.