Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

A specification for adding human and machine readable meaning to commit messages

conventionalcommits.org

Post reply on HN
Print view View original

21–30 of 49 posts

Re: A specification for adding human and machine readable meaning to commit messages

#21

Post by vbezhenar »

markrages wrote: post #5

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 con…

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.

Re: A specification for adding human and machine readable meaning to commit messages

#22

Post by larusso »

markrages wrote: post #5

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 con…

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.

Re: A specification for adding human and machine readable meaning to commit messages

#23

Post by Izkata »

jahsome wrote: post #9
markrages wrote: post #5

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 con…

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?

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).

Re: A specification for adding human and machine readable meaning to commit messages

#24

Post by Izkata »

Supermancho wrote: post #12
jahsome wrote: post #9

Earlier quoted context omitted.

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?

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.

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.

Re: A specification for adding human and machine readable meaning to commit messages

#25

Post by shoo »

ivan_gammel wrote: post #13

There’s a common convention that starts commit message with ticket numbers. Why tickets are not mentioned in the spec? This context is more important. Regarding choice of types: why „feature“ is shortened to „feat“? If there’s a type for feature, why another type is „fix“, not a „bug“? Semantically naming should be consistent. Automatic relationship with semver is questionable. Fix can be a change in architecture tha…

I completely agree that linking to additional supporting docs that explain requirements, design, etc is very helpful. Especially for the crew of poor bloody maintenance contractors trying to reverse engineer the system requirements and constraints from the commit history a decade or two into the future, after everyone else originally involved with hauling the system into production has escaped/retired/died/fled changing their names and CVs.

I've had some coworkers argue that the first line of the commit ("subject line" in git) is very important real estate, not to be wasted on a ticket reference, where it could instead hold a human readable summary. There's some merit to that. But they'd still include a reference to the ticket inside the body of the commit.

Depending on how excitable one's org is about creating and migrating between issue trackers, sometimes a ticket reference can still be very ambiguous. I've seen one enterprise project migrate between different JIRA instances within the space of a couple of years, where depending on which instance you plugged the same ticket reference into, you'd get a completely different ticket!

Re: A specification for adding human and machine readable meaning to commit messages

#26

Post by regularfry »

ivan_gammel wrote: post #13

There’s a common convention that starts commit message with ticket numbers. Why tickets are not mentioned in the spec? This context is more important. Regarding choice of types: why „feature“ is shortened to „feat“? If there’s a type for feature, why another type is „fix“, not a „bug“? Semantically naming should be consistent. Automatic relationship with semver is questionable. Fix can be a change in architecture tha…

> Implementation of non-functional requirements is not a fix, yet it does not introduce new features and thus not a minor version increment.

Bumping the minor version for this is fine in semver. It's a MAY in the spec.

Re: A specification for adding human and machine readable meaning to commit messages

#27

Post by masklinn »

markrages wrote: post #5

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 con…

> 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.

Re: A specification for adding human and machine readable meaning to commit messages

#28

Post by charrondev »

markrages wrote: post #5

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 con…

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.

Re: A specification for adding human and machine readable meaning to commit messages

#29

Post by masklinn »

zaroth wrote: post #18
ivan_gammel wrote: post #15

Earlier quoted context omitted.

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.

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!

> 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?

Re: A specification for adding human and machine readable meaning to commit messages

#30

Post by regularfry »

shoo wrote: post #25
ivan_gammel wrote: post #13

There’s a common convention that starts commit message with ticket numbers. Why tickets are not mentioned in the spec? This context is more important. Regarding choice of types: why „feature“ is shortened to „feat“? If there’s a type for feature, why another type is „fix“, not a „bug“? Semantically naming should be consistent. Automatic relationship with semver is questionable. Fix can be a change in architecture tha…

I completely agree that linking to additional supporting docs that explain requirements, design, etc is very helpful. Especially for the crew of poor bloody maintenance contractors trying to reverse engineer the system requirements and constraints from the commit history a decade or two into the future, after everyone else originally involved with hauling the system into production has escaped/retired/died/fled chang…

Jira integration is one place I've seen some real horrors - feature gets marked as "done" with a link to a git hash, then that patch gets bundled into a massive squash merge with a "changelog" that just says " merge 1/8/2022" and the feature branch deleted so the git hash gets lost. No traceability whatsoever.
Post reply on HN