3 ms·

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 t

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.

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.