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

The Lost Art of Commit Messages

seyhan.me

Post reply on HN
Print view View original

51–60 of 61 posts

Re: The Lost Art of Commit Messages

#51

Post by yaris »

Cthulhu_ wrote: post #21
rollcat wrote: post #8

Depends. Sometimes a one-liner or a reference to a ticket is enough. There are times when I make a one-line change and write a paragraph or two explaining why it had to be done. But these kinds of things often drown in the noise of a dozen other changes. If that one was important enough, I will reference it in an ongoing discussion or documentation, or at least include "read below:" on the first line. I usually see p…

A one-liner: sure. A ticket? No; ticket systems are transient and not always available. You shouldn't need to open an external system that may no longer exist in 20 years time (for example) to get the full context. Compare the Linux commit history, every commit has its full context and explanation and they do not rely on external systems.

Our ticket system survived almost 20 years and is useless anyway, because approximately half of the history consists of pairs like: commit 12345 ”fixed a bug, see ticket 54321” - ticket 54321 ”fixed by commit 12345”.

Re: The Lost Art of Commit Messages

#52

Post by HelloNurse »

The quality of commit messages depends on context. The author seems focused on bringing order to long freestyle messages, presumably for the purpose of accreting a rich but readable history log in long-lived branches, but not all commit messages are like that.

For example, when typical commits are about solving or implementing some support ticket, issue, new feature etc. that is documented elsewhere correct references are far more important than classification of the commit type or descriptive details; special commits (refactoring, chore, docs etc.) are easily noticeable because they don't reference a specific issue and many details are better omitted for the sake of deduplication.

  fix(ui): correct alignment on dashboard widgets
  
  - adjust CSS flex properties
  - test on multiple screen sizes
  
  Fixes #204
could be (on one line, easier to read in a massive log, and without redundantly describing the problem with misaligned widgets)

  #204 - adjusted CSS flex properties of dashboard widgets; tested on multiple screen sizes
or maybe, depending on what is expected to be explained in issue #204 or not, more technically precise:

  #204 - same CSS flex properties for all dashboard widget DIV elements; tested on 800*600, 1880*960 and 2900\*1600 browser windows but not on the standard smartphone emulators

Re: The Lost Art of Commit Messages

#53

Post by benji-york »

chrismorgan wrote: post #45
saagarjha wrote: post #12

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…

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

You might like top's commit messages, e.g., https://gitlab.com/procps-ng/procps/-/commit/e6f22569e9db16d...

commit e6f22569e9db16dbef7d9bdee5bb41b8cb7a03ca

Author: Jim Warner

Date: Tue Jul 23 00:00:00 2024 -0500

    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

Re: The Lost Art of Commit Messages

#54

Post by addisonbeck »

gherkinnn wrote: post #35

A dev culture that produces nothing but wip and fix bug commits (frequently adding unrelated refactors) will continue to produce noise but prefixed with chore(code): fix bug . I fail to see the benefit behind this and conventional commits. I do not understand why people insist on trowing inane technical solutions at social problems. It doesn't work.

`chore(code): fix bug` doesn't follow conventional commits, so it's not at great example for this point.

In my experience conventional commits tend to lower character counts and improve the readability of messages. `bug(auth): adjust XYZ` is shorter than `fix auth bug by adjusting XYZ`.

Re: The Lost Art of Commit Messages

#56

Post by drac89 »

Hojojo wrote: post #24

I quite like my current system. One word naming the topic or area or system that was changed, then colon separated with a very short sentence giving a summary of the changes, then two lines later (if necessary), a bullet point list of the most important/noteworthy changes, then an explanation for why a thing was changed (if any change in the commit warrants it). Honestly, I know most people won't go beyond the first…

Looks beautiful. And the best part is, if you ever need to fill out a PR template with what you did or list the changes, it becomes so much easier. You don’t even have to remember exactly what was changed, it’s all right there in the commit message.

Re: The Lost Art of Commit Messages

#57

Post by drac89 »

Cthulhu_ wrote: post #21
rollcat wrote: post #8

Depends. Sometimes a one-liner or a reference to a ticket is enough. There are times when I make a one-line change and write a paragraph or two explaining why it had to be done. But these kinds of things often drown in the noise of a dozen other changes. If that one was important enough, I will reference it in an ongoing discussion or documentation, or at least include "read below:" on the first line. I usually see p…

A one-liner: sure. A ticket? No; ticket systems are transient and not always available. You shouldn't need to open an external system that may no longer exist in 20 years time (for example) to get the full context. Compare the Linux commit history, every commit has its full context and explanation and they do not rely on external systems.

I agree maybe not adding the ticket link is better if you know that the system might not be available in the future.

You can not avoid it all the time but maybe It's better to use the PR description for that purpose.

Re: The Lost Art of Commit Messages

#58

Post by drac89 »

occz wrote: post #50

I'm not sure I'm entirely on board with this particular format, but I do agree with the larger point of well-crafted commit messages - and commits, for that matter - being an important quality feature in a project. I'd posit that well-structured commits are principally for the benefit of the reviewer of the code. Order your commits in a fashion that makes sense narratively, and give them meaningful commit messages. U…

And the best part is, if you ever need to fill out a PR template with what you did or list the changes, it becomes so much easier. You don’t even have to remember exactly what was changed, it’s all right there in the commit message.

Re: The Lost Art of Commit Messages

#59

Post by drac89 »

tobyhinloopen wrote: post #6

--message "wip" Why do we care about commit messages? I only read them when rebasing.

It's useful in case like if you ever need to fill out a PR template with what you did or list the changes, it becomes so much easier. You don’t even have to remember exactly what was changed it’s all right there in the commit message.

With structured comments, you can even use the AI to fill out the PR template easily and precisely.

Re: The Lost Art of Commit Messages

#60

Post by naavis »

tobyhinloopen wrote: post #47
naavis wrote: post #15

Earlier quoted context omitted.

They are incredibly helpful when you are trying to find where a bug was introduced, and trying to figure out why some piece of code is the way it is.

If you can’t figure it out based on the git blame and git diff, the code is incredibly unreadable. A comment in the code, or simply writing better readable code seems like a better investment. Besides, a few passes refactoring and your git history is ruined. No way you’ll find the original commit within any reasonable time frame. If I move the code to another function, your original commit message will be hard to tra…

I can only speak from my own experiences, but I have found commit messages extremely helpful, when they explain the "why" of the change. And as unfortunate as it is, many of us also have to work with unreadable codebases.
Post reply on HN