[markrages]

The examples given are more "what" changed than "why" it was changed. These are low-value commit messages because they are redundant with the content of the commit itself.

It is almost like signing all your commits with your name or the current date. (Yes, I had a coworker who did this.)

Better commit messages tell you what the situation was around the commit: Ticket number, or who wanted the change, or any other context that might tell you why the code was changed the way it was.

Consider the dev accessing your commit through "blame". What does that user need to hear? Not which file or subsystem was changed. But the reason there is a change in the first place.

My habit has been to prepare longer commit messages, a paragraph or two of explanatory text for that future developer, who is most likely future me.

Policy at my company now squashes all my carefully-prepared commit messages into the one-liner "Merged $BRANCHNAME into main". I will probably just switch to the three character commit message "WIP" like my coworkers have done.

[charrondev]

At my company we squash all merges and I’m the one that put the rule into effect. A few things to keep in my with squash merges (at least with GitHub)

- GitHub uses the pull requests title and description as the merge commit description, as well as linking to the pull request. This means all of our mainline commits now have links to relevant Jira tickets, context, change requests, and feedback on the PR. - The mainline commits are new linear and easy to read through, to the point where I was able to make an internal tool that can show everyone where every commit is at, with a nice description, and what stage in the production release cycle it’s at. - git bisect is a lot easier now. No one has to bissect through all kinds of “wip” or “fixed test for x platform in ci” commits. - most devs never have a need to rebase. Ever. This means devs can stack PRs against each other and test each others code together without having to deal with a rebase causing a bunch of pain. - All commits in our main branch now pass CI. - all commits in our main branch are now GPG signed by the org, without devs needing to configure commit signing locally.

[pfix]

Maybe it's my DevOps / System Engineering perspective, but most of the time when checking the history of the code, I care why a specific line changed - and squash commits don't help me get the granularity for that (e.g. why do we need 5 instead of 4 instances now) - most of the times, those changes are too small in the context of the full Pull Request / Merge, but matter 2 years later when you try to grok why something is the way it is.

So I prefer the flow of rebasing before merge. This way main stays linear and readable and you have the descriptive level at the commit level. The Context for the full merge can be found in the ticket corresponding to the change.

[cbovis]

"matter 2 years later when you try to grok why something is the way it is"

Sounds like the perfect use of an inline comment rather than change history?

[pfix]

True - but then I've seen way too many comments having no relation left to the code around them.

On the other hand the worst offenders are refactorings with the commit message "refactoring". Then you can go hunting. Then a comment would have helped.

In a perfect world we would have both, good inline comment, well written commit message and a ticket with more than a title.

[vbezhenar]

First line should provide short description of "what" changed. Because nobody's going to inspect every commit changes to find out what changed if all you need is quick glance at commit log.

After first line you can write all the additional information.

[pancrufty]

I think it's standard for juniors to think comments just need to rephrase code. Commits titles are just comments (about changes)

    // if ID exists in commits
    if (commits.has(id)) {

Big sigh every time I see this, especially if the code is "well-commented"

    // if ID exists in commits
    if (commits.has(id)) {
      // make no changes
      return
    }

    // add ID to commits
    commits.add(id)

    // log ID to console
    console.log(id)

On the other hand, LOCs through the roof, 10x developer right here.

[jahsome]

I've hit a couple shops in a row now where squashes are The Way. It's such a short-sighted and misguided policy.

I don't understand what is so appealing about a linear commit history. It's a fabrication of reality, and I have never been grateful for it, only enraged.

Why wouldn't you want to know what _actually_ happened? What is being gained besides an aesthetically pleasing "commits" tab on GitHub?

[Izkata]

As someone who does maintenance instead of new feature development: you're right. Squash merges are totally useless. I always want the real history, which lets me see when during the feature development the bug was actually introduced, and the original commit timestamps, which I can correlate to comments on the case.

There is never reason to squash. The best of both worlds is to always force a merge commit (disable fast-forward merges) and look at the log formatted whichever way you want (--first-parent shows people that linear history without destroying history).

[vbezhenar]

Linear history is the only sane way to have usable history. Merge spaghetti is a good way to ensure that nobody would ever being able to navigate it.

Squashing large number of commits is questionable practice, though.

[masklinn]

> Linear history is the only sane way to have usable history. Merge spaghetti is a good way to ensure that nobody would ever being able to navigate it.

1. you can have a linear history by rebasing then fast-forwarding onto the target

2. but it’s complete nonsense, learn your tools e.g. `git log --first-parent` (and how to merge), merge commits work perfectly fine

3. and importantly you can rebase then merge, which cleanly packages a set of changes behind a single merge commit without interspersing with other branches, and yet without losing the branche’s details

[jahsome]

I'm sorry, I don't mean to be dismissive, but I just can't read that as anything other than "doing it correctly makes it harder."

That sentiment is not IMHO a particularly potent argument for _anything_ related to engineering.

Accuracy, not convenience, should be the goal. If you need to make consuming the data more convenient, that should be the focus.

To be clear using the word "correctly' is putting a lot more confidence behind my opinion than I ever intended, i.e. I am open to counterpoints, and do not portend to think a one size fits all policy is realistic.

[alxmng]

You can list only merge commits to get a linear log, without destroying history.

[bloak]

Yes. I think the right way to do it is probably with "git log --first-parent", which will give you a linear history, and the linear history will contain only merge commits provided your project was configured to allow only merge commits. However, if you also allow squash or rebase merging then the linear history from "git log --first-parent" may contain commits that are not merges and will show the details of any PR that was rebase-merged. So, if you're going to allow merge commits at all, perhaps that's an argument for allowing only merge commits.

There's also "git log --merges" but that would presumably show any merge commits that happen to be present in a branch that is being merged so it wouldn't necessarily be linear.

If you disallow merge commits on GitHub, does that prevent a merge commit from being introduced as part of a rebase merge? If it doesn't, then presumably the only way to guarantee a linear history on GitHub is to allow only squash merging.

So, if you don't trust your developers to always do the right thing perhaps you should either only allow merge commits or only allow squash merging?

[alxmng]

Good points. Ideally, I prefer a workflow where features are branches and merged in, with fast forwarding disabled and rebasing used to keep feature branches updated. History is preserved, a linear history exists as merge commits, and merge commits also map cleanly to PRs.

[nazgul17]

You could do a rebase instead of a merge

[Supermancho]

Branch merge commit message is where you want the meaningful message. The individual commits are more or less noise for the vast majority of developers (half of which are below average). A useful system accounts for the most common case and it's not on the individual commit level.

[Izkata]

You do realize you're proposing "do extra work to prevent the history from being usable for the small percent who use it", right? The squashed history is lost, not hidden.

And those below-average developers probably aren't looking at the history at all anyway.

[Supermancho]

To be clear, I'm implying that a meaningful branch merge commit message is important. That's the change that matters for project history...which may or may not include a squashed history of the branch. The individual commit messages before that are for the developer(s) to manage as they see fit.

At any time, a developer might make another branch, then merge branches or squash the whole history of their branch or create a new branch and add the changes as if it was a fresh branch. Meaningful history is lost in those cases as well. Adding micro-managing process might get (more or less) predictable results, but it almost always pushes developers toward anti-patterns ensuring those predictable results are not what was intended.

[andrew_]

GitHub flow is a natural companion to squash merges as a rule.

[jrockway]

I'm a big anti-fan of this convention, but I'll quibble on some of the points. "what" is a good item for the first line of the commit. Not everyone has the luxury of shipping to prod from master; many people need to maintain backport branches, prepare releases, etc. Therefore, being able to quickly identify the commit you're looking to backport can be important. If one line of text can do that, then that's faster than reading the diff.

This doesn't mean a "why" shouldn't also be required.

Finally, I really dislike the specifics of conventional commits. "feat", "fix", and "docs" are not particularly interesting distinctions. Just put whatever you were going to put in parens and save yourself 6 bytes.

[masklinn]

> Policy at my company now squashes all my carefully-prepared commit messages into the one-liner "Merged $BRANCHNAME into main".

WTH? That’s the dumbest policy I’ve ever heard of. Who made this up?

On the other hand, a branch name can be 255 characters, time to get the entire thing in there.

[larusso]

I also preach this to every engineer who works in my team. The why is so important along with the context of one or multiple tickets depending on the project. But I‘m also a strong believer in linear history. When we squash commits from topic branches into the mainline we take the why commit message as the merge/squash commit message. I don‘t like the default here which just lists all messages in a row. My personal style changed here from crafting explicit clean commits on the topic branches which could just be merged to a single commit. The reason is that I actually don‘t care how often a file has changed for a given feature. If the change is too complicated it should be split up anyways. We work with Pull Requests in GitHub which means that the PR message becomes the place to describe the why message which gets picket as the merge commit message. I only saw benefits in my projects with this setup. The mainlines history is easy to understand and consists in best case only of PR squash messages. Change Notes can be generated quite easily and single changes are easier to revert (That really depends on the size of the change, I normally keep an eye on that) K think it is then also important that in a change requests not too many things are done at once. Want to fix a bug, do that. Do not introduce a new feature along with fixes for some random other part of the system. Fix that upfront or in a different PR/commit. So all in all I think long detailed commit messages plus squash commits are working together. You just need to pick when you do the work of writing these super long messages. I do it at the end when making ready to publish it as a PR and no longer 20 times during the development of said feature.

[larusso]

I wanted to add that I think writing a longer commit message with a description why a change is needed before opening a change request can also help the author to check one more time if the solution or reasoning is sound. Like a rubber ducky. It really helps to write down the message in a way to explain some other person why the change needs to be made and maybe with some more context why the specific solution was choosen. More often than not this one realized that the solution at hand might not be the best or one suddenly thinks about an easier/simpler solution. Because of this I tend to think about this message early. And it happened that I dropped some requests because I thought about an alternative route because I realized the change would bring to much complication etc. Because if it is hard to explain why a change is needed than something is slightly wrong. That is obviously different case by case and one shouldn't form a dogma around it.

[bryanrasmussen]

>These are low-value commit messages

I think they are more medium quality commit messages, low value would be significantly less informative than that.

Aside from that while I agree you should have ticket number etc. integration between ticketing system (generally Jira, let's be honest) and your git provider is probably non-existent so it is of less real value in finding what you what to find when looking through that git providers interface.

In fact if your commit message does not say what was done you will have to go into the commit to read the code and figure it out, which obviously is wasteful if you are trying to find the most likely commit in a dozen that caused a problem.

[superbaconman]

> What does that user need to hear? Not which file or subsystem was changed. But the reason there is a change in the first place.

Doesn't that belong in the code itself? Do we really want the intention of a change to sit under multiple levels of blame?

[masklinn]

> Doesn't that belong in the code itself? Do we really want the intention of a change to sit under multiple levels of blame?

Yes? How would you encode the reasons for a change and for the way the change was implemented in code, dozens of lines of comments and ending up with files which are 90% comments floating in the void long detached from any code they were relevant to (and which may not even exist anymore)?

[ivan_gammel]

It’s called traceability of requirements and is important part of post-release QA. At any given moment of time it must be possible to understand the reason for change down to a single line of code.

[zaroth]

That’s lovely and all, but can’t be a commit message, which is primarily about succinct human understanding and setting context.

A commit can certainly have computer readable metadata I presume!

[masklinn]

> That’s lovely and all, but can’t be a commit message

Of course it can.

> which is primarily about succinct human understanding and setting context.

You do know there is essentially no limit to how long a commit message is right?

[andrew_]

all of that sounds awful, I'm sorry for your experiences.

many repos are successfully using conventional commits in a way that's not low value, clear and concise in message, and useful in blame and walking history.