7 ms·

Information that can be automatically extracted from the delta is the least important part of a good commit message. I can figure that part out from looking at

by jefftk 4y ago

Information that can be automatically extracted from the delta is the least important part of a good commit message. I can figure that part out from looking at the commit later. Instead, what I really want to know is why you made the change. What is the context? What problem were you solving? Why this way and not other ways you might have solved the problem? A summary of what the change does is still useful, and I'm glad this can now be automated, but it's not the main benefit of a well written commit message.

nunobrito 4y ago
Was looking at the examples (link posted at another comment) and this addon seems like a good starting point for an accurate commit message. Starting point. After that it should up to the committer to make modifications and upstream the message. For those cases, seems good enough for me.
Karunamon 4y ago
What I have always been told for writing good commit messages is that the message should tell you what the commit does when applied to the code. The place for these what/why messages would appear to be in a ticketing system of some kind, referenced by ID in the commit message. What you're asking for would result in extremely bloated messages.
- singpolyma3 4y ago
  There's no meaningful limit on message length for a reason. Don't bury the context in some external system that may change or go offline, let it live in the commit where it is safe and easily accessible.
- baq 4y ago
  On the contrary, git commit messages and checked in docs are the only places that are guaranteed not to be lost to history. Ticketing systems change, get migrated to with data loss or are access limited. Git is forever. The commit message is a much better place for explaining what was done why than some obscure Jira instance.
- tablespoon 4y ago
  > The place for these what/why messages would appear to be in a ticketing system of some kind, referenced by ID in the commit message. No. It's best to assume that all information in your ticketing system will be totally lost. The commit message should have the "what/why" directly in them, because that's where you'll first look when you want to find that out (why add an extra hop), and it would require extreme incompetence (which is not unknown) to lose information stored there.
  - nazgul17 4y ago
    I agree at a gut level with this. Do you have a source that this is more widely believed? I would like to bring this to my tech lead.
    - ycombobreaker 4y ago
      Walk through a hypethetical ticketing system migration with your tech lead. Assume all external links are broken, and see how expensive it becomes to answer questions about your own codebase. "why did we add special case X? is it still applicable? It interferes with new feature request Y, can we remove it to reduce total risk/cost of implementing Y?" Integrating with another tool is fine, but not at the expense of your commit history!
    - tablespoon 4y ago
      > I agree at a gut level with this. Do you have a source that this is more widely believed? I would like to bring this to my tech lead. This was learned from hard experience. During my tenure, we've migrated corporate wikis/"collaboration systems" four times, and we've used at least as many ticket systems. We also migrated from webex to Teams a few years ago. Each migration resulted in at best a severe partial loss, and in some cases a total loss. The most stable resource is the codebase. Basically, whenever anyone does a migration for you, they will lose things, and they might even think losing them is a "clever" shortcut that will make them more efficient. Our recent documentation system migration only covered documents modified in the last year as a corporate cost-saving measure, and we were on our own for everything else. Weak/understaffed teams did a bad job. They retroactively implemented a retention policy on Webex that wiped out a lot of valuable recordings, and then the coup-de-grace was the migration to MS Teams, which wiped almost everything else (basically everything that the original recorder didn't conscientiously download and save). We recently migrated to MS ADO as our work tracking system, and that was the only time I've seen old stories/bugs migrated at all, and even then we still lost all embedded images. Here's a list of things in order of least to most likely to be lost: 1. Head/tip of your project in source control 2. Source history 3. Documentation stored in a central location as files you can easily copy 4. Documentation stored in some system (like a wiki) 5. Tickets/stories in your work tracking system
- xorcist 4y ago
  > extremely bloated messages Please read a few commit messages for the git project itself. That is how git was designed to be used. Maybe that provides some perspective of just how bloated commit messages can be, but also how useful they then become.
jnsie 4y ago
Haven't tried this solution but my first thought was of those (.NET) libraries that would generate comments using a functions signature (function name, parameter name, etc.). Remember some senior devs at the company I worked for at the time being mesmerize and overusing this. We ended up with comments that could easily be inferred from reading the signature...
- jimmaswell 4y ago
  I like those in general because you can hover over a function call in visual studio to see a description.
savolai 4y ago
A summary can still help you remember the parts of what you did and more accurately fill in the why.
DogLover_ 4y ago
I think you would be surprised how PRs work in many companies. We are encouraged to write small PRs and many will have automated tools that points to a Jira ticket in the description or as a comment. For this reason many leave empty descriptions. In such cases this would still help.
warpech 4y ago
Came here to make the same comment. There is a great blog post about it: https://dev.to/jacobherrington/how-to-write-useful-commit-messages-my-commit-message-template-20n9 https://dev.to/jacobherrington/how-to-write-useful-commit-me... It boils down to the following commit message template: <what you changed> because <why it was needed>
- _0w8t 4y ago
  From my experience people rarely read the commit message s, so it is better to put the why part into comments in the code, not git history. I mostly write the detailed why part in the commit only for refactoring changes.
  - nazgul17 4y ago
    Well, sometimes, changes are "events" and only make sense to know in the context of the state of the codebase at the time.
  - JBorrow 4y ago
    depends, if you are bisecting the commit messages are very helpful
    - TillE 4y ago
      Yeah it's not either/or, you really want both.
  - ycombobreaker 4y ago
    My experience is that many changes span several blocks of code in a repo, so there's not always one single location to put the comment. There's also a blessing in that git commits don't need to be maintained like comments. Comments can drift if not maintained. A commit is only observed in-context. Most developers seem to be poor "commit historians" by default, I'll admit. If you have the energy and consistency to enforce good history, it eventually becomes self-sustaining.
  - phyzome 4y ago
felipelalli 4y ago
On my tests the GPT3 is able to understand the whole context and give a very good commit message.
- nuclearnice3 4y ago
  Do you think it was able to answer jefftk's questions, especially * What problem were you solving? * Why this way and not other ways you might have solved the problem? Or do you think those aren't usually needed for a very good commit message?
  - ilyt 4y ago
    > * What problem were you solving? That the ticket was open > * Why this way and not other ways you might have solved the problem? This is first one that worked. There, that's those answers covered for like 80% of the developers
    - deleted 4y ago
      [deleted]
Waterluvian 4y ago
I disagree. Unless there’s some smarter way to do this, I use the commit messages to find the kinds of historical changes I’m curious about. I want to know what changed. I’m not sure how one would do this unless they’re looking at every commit. The “why” goes into the PR and more importantly, engineering documentation and inline comments. Plus, a commit message seems woefully plain and too short to properly communicate these things. The beauty is that this isn’t prescribed. We can all do what makes sense for our contexts.
- catiopatio 4y ago
  > The “why” goes into the PR … This just ensures that the “why” is lost when someone comes looking years later. From experience, SCM history is far more durable than just about any other work product we produce. Over five decades later, commit history was still available for the Unix sources and could be reconstructed: https://github.com/dspinellis/unix-history-repo https://github.com/dspinellis/unix-history-repo I’ve used 35-year-old commit messages to help understand a long-standing issue, decades after all other related organization tooling and data had disappeared.
corytheboyd 4y ago
This commit sets the value of variable x to 10 on line 253 of the file main.go

by jefftk 4y ago

nunobrito 4y ago

Was looking at the examples (link posted at another comment) and this addon seems like a good starting point for an accurate commit message. Starting point. After that it should up to the committer to make modifications and upstream the message. For those cases, seems good enough for me.

Karunamon 4y ago

What I have always been told for writing good commit messages is that the message should tell you what the commit does when applied to the code. The place for these what/why messages would appear to be in a ticketing system of some kind, referenced by ID in the commit message. What you're asking for would result in extremely bloated messages.

singpolyma3 4y ago
There's no meaningful limit on message length for a reason. Don't bury the context in some external system that may change or go offline, let it live in the commit where it is safe and easily accessible.
baq 4y ago
On the contrary, git commit messages and checked in docs are the only places that are guaranteed not to be lost to history. Ticketing systems change, get migrated to with data loss or are access limited. Git is forever. The commit message is a much better place for explaining what was done why than some obscure Jira instance.
tablespoon 4y ago
> The place for these what/why messages would appear to be in a ticketing system of some kind, referenced by ID in the commit message. No. It's best to assume that all information in your ticketing system will be totally lost. The commit message should have the "what/why" directly in them, because that's where you'll first look when you want to find that out (why add an extra hop), and it would require extreme incompetence (which is not unknown) to lose information stored there.
- nazgul17 4y ago
  I agree at a gut level with this. Do you have a source that this is more widely believed? I would like to bring this to my tech lead.
  - ycombobreaker 4y ago
    Walk through a hypethetical ticketing system migration with your tech lead. Assume all external links are broken, and see how expensive it becomes to answer questions about your own codebase. "why did we add special case X? is it still applicable? It interferes with new feature request Y, can we remove it to reduce total risk/cost of implementing Y?" Integrating with another tool is fine, but not at the expense of your commit history!
  - tablespoon 4y ago
    > I agree at a gut level with this. Do you have a source that this is more widely believed? I would like to bring this to my tech lead. This was learned from hard experience. During my tenure, we've migrated corporate wikis/"collaboration systems" four times, and we've used at least as many ticket systems. We also migrated from webex to Teams a few years ago. Each migration resulted in at best a severe partial loss, and in some cases a total loss. The most stable resource is the codebase. Basically, whenever anyone does a migration for you, they will lose things, and they might even think losing them is a "clever" shortcut that will make them more efficient. Our recent documentation system migration only covered documents modified in the last year as a corporate cost-saving measure, and we were on our own for everything else. Weak/understaffed teams did a bad job. They retroactively implemented a retention policy on Webex that wiped out a lot of valuable recordings, and then the coup-de-grace was the migration to MS Teams, which wiped almost everything else (basically everything that the original recorder didn't conscientiously download and save). We recently migrated to MS ADO as our work tracking system, and that was the only time I've seen old stories/bugs migrated at all, and even then we still lost all embedded images. Here's a list of things in order of least to most likely to be lost: 1. Head/tip of your project in source control 2. Source history 3. Documentation stored in a central location as files you can easily copy 4. Documentation stored in some system (like a wiki) 5. Tickets/stories in your work tracking system
xorcist 4y ago
> extremely bloated messages Please read a few commit messages for the git project itself. That is how git was designed to be used. Maybe that provides some perspective of just how bloated commit messages can be, but also how useful they then become.

jnsie 4y ago

Haven't tried this solution but my first thought was of those (.NET) libraries that would generate comments using a functions signature (function name, parameter name, etc.). Remember some senior devs at the company I worked for at the time being mesmerize and overusing this. We ended up with comments that could easily be inferred from reading the signature...

jimmaswell 4y ago
I like those in general because you can hover over a function call in visual studio to see a description.

savolai 4y ago

A summary can still help you remember the parts of what you did and more accurately fill in the why.

DogLover_ 4y ago

I think you would be surprised how PRs work in many companies. We are encouraged to write small PRs and many will have automated tools that points to a Jira ticket in the description or as a comment. For this reason many leave empty descriptions. In such cases this would still help.

warpech 4y ago

Came here to make the same comment. There is a great blog post about it: https://dev.to/jacobherrington/how-to-write-useful-commit-messages-my-commit-message-template-20n9 https://dev.to/jacobherrington/how-to-write-useful-commit-me... It boils down to the following commit message template: <what you changed> because <why it was needed>

_0w8t 4y ago
From my experience people rarely read the commit message s, so it is better to put the why part into comments in the code, not git history. I mostly write the detailed why part in the commit only for refactoring changes.
- nazgul17 4y ago
  Well, sometimes, changes are "events" and only make sense to know in the context of the state of the codebase at the time.
- JBorrow 4y ago
  depends, if you are bisecting the commit messages are very helpful
  - TillE 4y ago
    Yeah it's not either/or, you really want both.
- ycombobreaker 4y ago
  My experience is that many changes span several blocks of code in a repo, so there's not always one single location to put the comment. There's also a blessing in that git commits don't need to be maintained like comments. Comments can drift if not maintained. A commit is only observed in-context. Most developers seem to be poor "commit historians" by default, I'll admit. If you have the energy and consistency to enforce good history, it eventually becomes self-sustaining.
- phyzome 4y ago

felipelalli 4y ago

On my tests the GPT3 is able to understand the whole context and give a very good commit message.

nuclearnice3 4y ago
Do you think it was able to answer jefftk's questions, especially * What problem were you solving? * Why this way and not other ways you might have solved the problem? Or do you think those aren't usually needed for a very good commit message?
- ilyt 4y ago
  > * What problem were you solving? That the ticket was open > * Why this way and not other ways you might have solved the problem? This is first one that worked. There, that's those answers covered for like 80% of the developers
  - deleted 4y ago
    [deleted]

Waterluvian 4y ago

I disagree. Unless there’s some smarter way to do this, I use the commit messages to find the kinds of historical changes I’m curious about. I want to know what changed. I’m not sure how one would do this unless they’re looking at every commit. The “why” goes into the PR and more importantly, engineering documentation and inline comments. Plus, a commit message seems woefully plain and too short to properly communicate these things. The beauty is that this isn’t prescribed. We can all do what makes sense for our contexts.

catiopatio 4y ago
> The “why” goes into the PR … This just ensures that the “why” is lost when someone comes looking years later. From experience, SCM history is far more durable than just about any other work product we produce. Over five decades later, commit history was still available for the Unix sources and could be reconstructed: https://github.com/dspinellis/unix-history-repo https://github.com/dspinellis/unix-history-repo I’ve used 35-year-old commit messages to help understand a long-standing issue, decades after all other related organization tooling and data had disappeared.

corytheboyd 4y ago

This commit sets the value of variable x to 10 on line 253 of the file main.go