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

31–40 of 49 posts

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

#31

Post by masklinn »

superbaconman wrote: post #11
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…

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

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

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

#32

Post by alxmng »

vbezhenar wrote: post #20
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?

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.

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

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

#33

Post by bryanrasmussen »

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…

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

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

#34

Post by kkoncevicius »

Interesting, I am using a similar convention, but for GitHub issue labels, not commit messages [1]. Then, the commit messages often just refer to the issue number as a reference.

[1]: http://karolis.koncevicius.lt/posts/improving_github_issue_l...

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

#35

Post by diarrhea »

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…

You would have a painful time if large but innocuous architectural changes introduced major version bumps. Semantic versioning is how many packaging ecosystems nowadays work and decide compatibility. There is only one question to answer: Did the architecture change change the public API? No: even if this was an entire application rewrite, users don’t care. This is not a new major. Perhaps not even a minor (this is subjective I guess). Yes: it’s a breaking change and warrants a major version bump. So the scale of changes is sometimes at odds with the scale of the resulting version bump. Huge changes might not even be fixes, single-line changes might result in major version bumps. All this is highly important for libraries to adhere to. Binaries/programs possibly less so.

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

#36

Post by jrockway »

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

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

#37

Post by larusso »

larusso wrote: post #22
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 s…

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.

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

#38

Post by pancrufty »

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

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

#39

Post by nazgul17 »

vbezhenar wrote: post #20
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?

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.

You could do a rebase instead of a merge

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

#40

Post by pfix »

charrondev wrote: post #28
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 mainli…

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.

Post reply on HN