[eikenberry]

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

[ralferoo]

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.

[andrybak]

The difference is that the Jira ticket is for everyone involved in a project (business analyst, UI designer, QA, support, DBA), while commit messages are written with developers being almost exclusive audience. PRJ-123 might explain why an end user might need it, but the commit message explains why the change (diff) is the way that it is. The ticket answers requirements-level questions, the commit message answers code-level questions. Commit messages are useful both during the review and when a future maintainer is reading the code.

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

Different commits do different things, so require different justifications. Here's a fictional example to demonstrate:

First commit:

    [PRJ-123] Server: extract class Foo
    
    In the next commit, we're going to need to re-use the foo logic from
    class Bar. Extract new class Foo from Bar to make it available for
    re-use.

Second commit on the same ticket

    [PRJ-123] Server: use Foo in Baz
    
    The users of BazClient need to be able to see foo information in the
    baz dialog.  Include Foo in the data sent by class Baz in the server.

Side note: the user might not even know that they are looking at Foo and Baz, it might be called something else in the UI they are shown. Whether or not this needs to be included in the commit message depends on the situation.

And later in a commit fixing a bug:

    [PRJ-456] Server: check ID for null in Foo
    
    When class Foo was extracted from Bar in commit deadbeef ([PRJ-123]
    Server: extract class Foo, 2026-06-06), a null check for the field
    ID got lost by accident.
    
    Check the field ID for null in class Foo to avoid a
    NullPointerException when a foo event is sent to Baz.

[ralferoo]

Personal preference I guess, but to me all of those commit messages are way too wordy. I'd probably have:

  [PRJ-123] Refactor Foo out from Bar

  [PRJ-123] Include Foo data in BazClient

  [PRJ-456] Null-guard on Foo ID to avoid data loss
  Bug introduced in commit deadbeef

And then in PRJ-456, I'd also have the comment about bug introduced in commit deadbeef, and link the two JIRAs if it was significant, or just mention it in a comment for a minor fix.

For me personally, nothing else in your commit messages adds value that can't be seen trivially from glancing at the changes.

[andrybak]

Git is more robust than Jira. Git log is accessible offline. Jira descriptions exist only as long as people managing the Jira instance are competent and are migrating the necessary data correctly when migrations are needed. Even migrations from one Jira instance to another (e.g. when companies get acquired and two Jira servers get merged) can be extremely brittle.

It's fair that maybe such simple trivial changes don't deserve such a wordy commit message. But these are just fictional examples that I came up with on the spot. Refactorings, new features, and bugfixes can all have various levels of complexity.

A good commit message helps answer the "why?" questions first and foremost. If a diff is fairly large, pointing out the most important change can be useful. Explanations for non-trivial dataflow can sometimes not make sense in separate documentation, but still be relevant in a commit message.

[dinfinity]

> Git is more robust than Jira.

Much of such issue tracking systems may be better in the repo in the first place. A Jira issue could just be a markdown file committed in the repo. A code review could just be commits of inline remarks/comments.

Maybe there is some value to slapping on a web interface on top of that data for ease of use, but as to where the data lives I'm leaning towards putting everything in repo.

[atq2119]

Interesting to see somebody argue out in the wild for what I have been subjected to in the past and have long considered absolute worst practice.

It may be that my perspective is different because my work tends to be in "hard" foundational software (think OS components and programming language tool chains). It's not that customer requirements aren't a thing at all in that kind of work, but they tend to be far removed from the day-to-day and instead, mechanical sympathy rules supreme.

Commit messages need to focus on the software, not on the trappings of the process by which it evolves. Links to tickets can provide helpful context especially for bug fixes, but they belong in the commit message footer.

Your last paragraph is absolutely an anti-pattern at least in this work. If the implementation of a new feature is split over multiple changes, then surely there is something different and important to say about each of those changes. Does your split even make sense otherwise?

[ralferoo]

As I said at the beginning of my first post higher up, different companies have different requirements, and there's no one right solution.

But as for the last point, many companies prefer constant integration of work in progress (perhaps with new functionally disabled) for development work that can take multiple weeks, rather than working entirely in a feature branch and introducing a massive change in one go, especially if it's required refactoring work to existing code. On such codebases, my commit frequency would typically be at least a couple of times per week, perhaps a couple a day in some cases.

So, while each commit will have a commit message explaining the change, none of those commits would be a sensible place to try to explain the justification for the work, something which I was already arguing shouldn't be in commit messages at all. The last point was an attempt to show that it makes even less sense to try to replicate the why of the feature requirement in the commit message at all. That is already documented in the ticketing system, the commit message should contain a summary of what changed, to aid a later developer trying to track down a bug.

From your third paragraph, it seems that we largely agree, you just disagree that the information about the ticket a change relates to is important enough for the subject line. If it was a URL link, I'd agree because they are long and messy, but honestly a JIRA reference like [PRJ-123] doesn't use much space and putting it on the subject line seems the best compromise to me, because I consider it mandatory. But if your company prefers a different policy, that's fine too - different companies don't all have to do the same thing.

FWIW, I've also worked in what you call '"hard" foundational software'. In fact, that's exactly where I was first exposed to this policy, recognised it was better than previous systems in previous companies for traceability, and later advocated it in other companies with smaller teams, and also use it myself on my one-man projects.

[saltcured]

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]

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]

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)

[rootnod3]

That's where something like Fossil is nice, because the tickets are part of the repo.

[bluGill]

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]

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]

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]

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]

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]

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

[mmcnl]

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.

[xorcist]

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

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.

[jsve]

You can put that in the body of the commit message, not everything has to go in the subject line.

[eikenberry]

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.