3 ms·

> The only thing I've found useful, and which the article doesn't even consider, is a link / id for the relevant change request. The commit already contains all

> The only thing I've found useful, and which the article doesn't even consider, is a link / id for the relevant change request. The commit already contains all the information about what was done in the change, what's missing is the context about why. The "why" is THE thing that needs to go in the git commit message. Capturing "why" is the entire point of that message and slapping a link to some external (and eventually absent) resource is not a good substitute.

mmcnl 4mo ago
It is a good substitute. 1. Usually the commit message is often too short to capture the "why" adequately. 2. It is very beneficial to capture the why in one single source of truth, and that usually is not the Git commit message in a business context. Hate on Jira all you want, but if you capture the "why" there, you can add comments, view history, add rich context, link dependencies, add rich context, etc. Can't do that in a Git commit message.
- jsve 4mo ago
  You can put that in the body of the commit message, not everything has to go in the subject line.
- eikenberry 4mo ago
  My ire is more directed at github PRs than Jira... but the same basic idea applies. You want a single source of truth and you want that as close to the origin (the code) as possible. Your history, dependencies, etc. are all in git already and can be highlighted there if appropriate. For general comments, git notes covers that. Business (ie. $work) will dictate whatever it wants and that is what get used but for anything I personally have control over, everything goes in the repo itself to prevent platform lock-in. For example, github's been going downhilll lately but all those projects with their history in PRs, etc. now needs to exfiltrate all that data somehow.
- xorcist 4mo ago
  Jira contains discussion and requirements. It can meander for months before the right action is chosen. It can be important to have background, but it replaces the mailing list discussion that led up to the change, it does not replace the commit message. The commit message is writen in retrospect and is written for someone with the code in front of them to explain why this change was made, and why it was done in this particular way. If your commit message is too short then than is your problem right there. The easy fix is you taking five seconds out of your busy day to save an hour for you readers. Have you seen how commit messages are written for git itself, or for the Linux kernel? Let me help you by linking the currently latest commit in the github mirror of git, it is not chosen to be particularly good or bad but is pretty representative of how git developers write commit messages: https://github.com/git/git/commit/b809304101 https://github.com/git/git/commit/b809304101 As you can see, without knowing much of the specifics of the code, we can get an idea why this change was made the way it was. There is a certain art to writing short and concise commit messages, but the same is true for code itself. Some, but comparably very little, practice is required.
bluGill 4mo ago
I find bug trackers and source control fad change several times over the life of my code. A number from a ticket system we no longer use is not helpful.
- sokoloff 4mo ago
  But a number from a ticket system you are using is helpful and vastly more log messages will be read during the time when it’s active than after it’s been retired/replaced.
  - bluGill 4mo ago
    The switch was too recent in my case, I'm still seeing many numbers from the old system that I can't look up.
    - ralferoo 4mo ago
      You should shout at your project managers then. The data in the ticket system should be considered important as it's the primary interface through which developers, QA and design share information.
      - bluGill 4mo ago
        They have the data but the numbers restarted at 1 and search in the new system isn't good. I think they all agree the old system was better - but the new license terms were unacceptable so we left anyway.
        sokoloff 4mo ago
        Restarting at 1 makes sense only if you think you’re going to run out of integers. I can’t fathom why part of the deployment of the new system wasn’t to re-seed to the current ticket number or an easy-to-remember integer (hopefully via database, but also ok even if via a Selenium for loop to pull 19,999 tickets to burn the numbers in the new system).
ralferoo 4mo ago
Respectfully, I disagree. A good commit message to me is something like: [PRJ-123] Changed blah to foo Blah didn't handle the wangle flange properly in some cases, foo is a better fit for customer requirements. The "why" that justifies the change, is already contained in the JIRA ticket PRJ-123 and explains exactly what the customer requirement was that necessitated the change. It will almost certainly contain a lot of detail that isn't relevant to the commit message, because that isn't the place to be documenting customer requirements, and probably relates to a number of other tickets. Perhaps the code itself might have a comment explaining the code change, if it's a non-obvious implementation, but otherwise the ticket is the best place for that information. Additionally, if a change requires multiple commits, you don't want to be repeating the justifications for the entire feature in every commit message. It's redundant. But the commits will all be tied together by the ticket reference in the commit message.
- saltcured 4mo ago
  Hah, maybe its the difference between why as in "this addresses problem X" and why as in "because those jerks in pre-sales sold another imaginary product" I think the commit ought to describe the purpose of the change in terms of its result for the software's intended use. Feel free to hide the business/political drama behind a ticket number. This gets down to a more fundamental tension. Are commit messages to communicate between developers? To communicate from developer to consumer? Or some kind of project manager golem? In practice, it is usually some constantly wandering attempt to be a blend of these.
  - ralferoo 4mo ago
    The last part is easy to answer. Commit messages are solely for developers IMHO. The communication between developer and customer / product manager should be via the ticket system. That said, knowing the commit ID something is fixed in, so that the PM can track what build it emerges in is useful.
- lelandfe 4mo ago
  3 years later. You are working on some old project that apparently is erroring. Through a git bisect, you find a commit that references JIRA, though your company uses Linear. You sigh, and start reading the diff. (Adapted from real life events)

mmcnl 4mo ago

It is a good substitute. 1. Usually the commit message is often too short to capture the "why" adequately. 2. It is very beneficial to capture the why in one single source of truth, and that usually is not the Git commit message in a business context. Hate on Jira all you want, but if you capture the "why" there, you can add comments, view history, add rich context, link dependencies, add rich context, etc. Can't do that in a Git commit message.

jsve 4mo ago
You can put that in the body of the commit message, not everything has to go in the subject line.
eikenberry 4mo ago
My ire is more directed at github PRs than Jira... but the same basic idea applies. You want a single source of truth and you want that as close to the origin (the code) as possible. Your history, dependencies, etc. are all in git already and can be highlighted there if appropriate. For general comments, git notes covers that. Business (ie. $work) will dictate whatever it wants and that is what get used but for anything I personally have control over, everything goes in the repo itself to prevent platform lock-in. For example, github's been going downhilll lately but all those projects with their history in PRs, etc. now needs to exfiltrate all that data somehow.
xorcist 4mo ago
Jira contains discussion and requirements. It can meander for months before the right action is chosen. It can be important to have background, but it replaces the mailing list discussion that led up to the change, it does not replace the commit message. The commit message is writen in retrospect and is written for someone with the code in front of them to explain why this change was made, and why it was done in this particular way. If your commit message is too short then than is your problem right there. The easy fix is you taking five seconds out of your busy day to save an hour for you readers. Have you seen how commit messages are written for git itself, or for the Linux kernel? Let me help you by linking the currently latest commit in the github mirror of git, it is not chosen to be particularly good or bad but is pretty representative of how git developers write commit messages: https://github.com/git/git/commit/b809304101 https://github.com/git/git/commit/b809304101 As you can see, without knowing much of the specifics of the code, we can get an idea why this change was made the way it was. There is a certain art to writing short and concise commit messages, but the same is true for code itself. Some, but comparably very little, practice is required.

bluGill 4mo ago

I find bug trackers and source control fad change several times over the life of my code. A number from a ticket system we no longer use is not helpful.

sokoloff 4mo ago
But a number from a ticket system you are using is helpful and vastly more log messages will be read during the time when it’s active than after it’s been retired/replaced.
- bluGill 4mo ago
  The switch was too recent in my case, I'm still seeing many numbers from the old system that I can't look up.
  - ralferoo 4mo ago
    You should shout at your project managers then. The data in the ticket system should be considered important as it's the primary interface through which developers, QA and design share information.
    - bluGill 4mo ago
      They have the data but the numbers restarted at 1 and search in the new system isn't good. I think they all agree the old system was better - but the new license terms were unacceptable so we left anyway.
      - sokoloff 4mo ago
        Restarting at 1 makes sense only if you think you’re going to run out of integers. I can’t fathom why part of the deployment of the new system wasn’t to re-seed to the current ticket number or an easy-to-remember integer (hopefully via database, but also ok even if via a Selenium for loop to pull 19,999 tickets to burn the numbers in the new system).

ralferoo 4mo ago

Respectfully, I disagree. A good commit message to me is something like: [PRJ-123] Changed blah to foo Blah didn't handle the wangle flange properly in some cases, foo is a better fit for customer requirements. The "why" that justifies the change, is already contained in the JIRA ticket PRJ-123 and explains exactly what the customer requirement was that necessitated the change. It will almost certainly contain a lot of detail that isn't relevant to the commit message, because that isn't the place to be documenting customer requirements, and probably relates to a number of other tickets. Perhaps the code itself might have a comment explaining the code change, if it's a non-obvious implementation, but otherwise the ticket is the best place for that information. Additionally, if a change requires multiple commits, you don't want to be repeating the justifications for the entire feature in every commit message. It's redundant. But the commits will all be tied together by the ticket reference in the commit message.

saltcured 4mo ago
Hah, maybe its the difference between why as in "this addresses problem X" and why as in "because those jerks in pre-sales sold another imaginary product" I think the commit ought to describe the purpose of the change in terms of its result for the software's intended use. Feel free to hide the business/political drama behind a ticket number. This gets down to a more fundamental tension. Are commit messages to communicate between developers? To communicate from developer to consumer? Or some kind of project manager golem? In practice, it is usually some constantly wandering attempt to be a blend of these.
- ralferoo 4mo ago
  The last part is easy to answer. Commit messages are solely for developers IMHO. The communication between developer and customer / product manager should be via the ticket system. That said, knowing the commit ID something is fixed in, so that the PM can track what build it emerges in is useful.
lelandfe 4mo ago
3 years later. You are working on some old project that apparently is erroring. Through a git bisect, you find a commit that references JIRA, though your company uses Linear. You sigh, and start reading the diff. (Adapted from real life events)