I've seen far too many people think that putting the ticket id into the commit message can be a replacement for writing a good commit message. I've even seen people think that "Fix #123" is all they need to put in there.
The commit history should be the primary source of truth for what changes have happened.
I've also been at orgs where they've switched from one ticket tracking software to another, and haven't maintained history, or even when they do, the ticket ids and up changing afterward.
Regarding migrating to new issue tracking systems, "not maintaining history" is absolutely a critical fail at that org. Every decent tracking system I can think of has ways to import issues from other systems - skipping that step is pretty inexcusable for all but the earliest stage projects. And the vast majority of them have ways to transparently map ticket IDs. E.g. in Jira if you migrate a project and give it a new project ID, the old IDs can still be used and they will transparently redirect to the new ID.
They are too long to fit into a title but fit nicely into the body text…
See https://bugs.com/8765309
…with the advantage that many tools already know how to make these magic strings into clickable links. No need to rely on parsing #<id> or !<id> or whatever.The first place was pre-jira popularity and we maintained our own system, or used systems from our clients.
The second place was a game studio and had many more bugs than any other place I've worked. One game title we had, we had around 29k tickets, and cleared out 7k in our biggest week. The speed of the UI actually impacted the effectiveness of our throughput at one point. We started with Traq, then hansoft. But I think jira won out over hansoft due to the ability to customize it and then sony just maintaining a jira for us that their teams used to coordinate with us, so kinda a no brainer.
The last one is interesting as Amazon has many tracking systems, and even if you use jira, over time the jiras were so crowded they had several, we used jira-4 (out of 7 or 8) before I setup one for our org. At twitch we've been consistent on our use of one jira instance since i've been there, but we've changed the url I think 4 times since during my tenure.
In all of these places we've had many codebases that outlasted the urls. All of those places I've been we just use the short numbers like AND-3421.
In the cases I needed to click them I could just use alfred or a tampermonkey script. It's a lot shorter as well.
1. The perfunctory kind, where you make the ticket just to track the work, when the work is already obvious and well-known. There's no discussion in the ticket; you just create it, do the work, and close it.
2. The kind where you end up with a lot of back and forth between various stakeholders about what the requirement/feature/whatever is, or about how to reproduce a bug that needs to be fixed, or something like that. In this case, there's a lot to wade through, and while the history can be an interesting artifact as to how everyone got to the end state of the git commit that closed the issue, it's overly wordy.
And sure, there are tickets that are somewhere in between.
But ultimately I think the kinds of tickets that are closer to #1 don't even need a reference in the git commit, because pretty much all of the ticket's text should be in the commit message anyway. And for #2, there's way too much information in the ticket anyway; it should be distilled down to the important details for the commit message. And yes, a reference to the ticket should be provided as well, for people who want or need to wade in to get the full context. But that goes at the end of the commit message, after the change has been adequately described.
> "not maintaining history" is absolutely a critical fail at that org
Absolutely agree! But that doesn't mean it doesn't happen (and often!), and when it does, all your ticket references become useless, so you'd better have a good, thorough description in the commit message, or all context is lost.
> Every decent tracking system I can think of has ways to import issues from other systems
But almost universally you end up with new ticket IDs when that happens, so the references in the commit messages become useless. Sure, many of those importers will start off the description in the imported ticket with something like "Imported from JIRA ID FOO-123", but that requires extra effort to search. Sure, if you migrate from one instance of JIRA to another instance of JIRA, there are ways to keep those links intact/redirected, but I'm not aware of any ticketing system that somehow preserves URLs/IDs from completely different ticketing systems.
Not really, because even tickets without body or comments have links. At the minimum, a decently configured tracker must have links to all the other commits involved. And even when there is only one commit, it's useful information unless all tickets in your project are done in exactly one commit.
We don't call them tickets, because we aren't "ticket takers" and we don't expect them to contain all of the information -- how could they, it's our job as implementers to discover and understand. They are work items, and they are placeholders for conversations. We use high-bandwidth communication to reduce, and often eliminate, the "back and forth" that is so common on many teams.
We keep logs of our work both on a personal and project level, which includes decisions from these high-bandwidth conferences. When we have stakeholders that are hard to get meetings with we schedule a regular cadence with them so we can get their time at least once a day/week/whatever.
Sometimes it's not a critical fail; sometimes it's a permissions issue: only a small subset of developers have access to the original ticket.
The fix is simple: write good commit messages. Don't assume the person reading the commit message has access to the ticket.
But more importantly, this thread somehow got off the rails into a debate about only leaving a ticket ID in the commit. I never argued for that, and I don't think anyone else did either. A commit message should still state what happened, code-wise, in a particular commit (e.g. one ticket may require many commits or PRs). But I still think the ticket ID is the most important piece of info in the message, as it ties the commit to important context about why the code change was made in the first place.
It's just super impractical. The work is discussed / documented in the project management systems, I'm not going to copy it extra (from design document, the ticket description, ticket discussion, screenshots) for the SCM. Too much work, too small benefit.
> I've also been at orgs where they've switched from one ticket tracking software to another, and haven't maintained history, or even when they do, the ticket ids and up changing afterward.
I've been in orgs where they've switched SCM and didn't keep history. Neither should happen.
I agree, it is super impractical to have to read the whole discussion again instead of having a comprehensive description of the agreed upon result of that discussion. Therefore, writing good commit messages is really valuable.
But that’s the whole point of a version control system. That’s all it is for.
If that is super impractical then our VCSs (Git and others) must be too impractical to use.
That’s interesting. Is the documentation in the project management system? What tool is that?
Exactly this! In our company's commit messages, I start with the component or file I've touched, such as 'Config: update year in example value' or 'make check: reduce false positives for erroneous backslash detector' (context: we clone the repository for short-lived projects which result in a document, so having an up-to-date year value is handy and we check the PDF build for common issues)
Not only does it help others find when a particular change was made, it also gives context when they're scratching their head "what do you mean updated year value, where do we hardcode year values? ... Oooh, in the config file where we keep example values, right that makes sense!"
This also incorporates what u/twodave said in a sibling thread (https://news.ycombinator.com/item?id=38832441):
> when I'm looking at blame/history I'm usually very aware of what the code is doing already. My question at those times is less about "what" and more about "why".
By saying the change intends to reduce false positives, the regex change makes a lot more sense. Commit messages are often in the style of "improved backslash detector". You might wonder why the old version was broken, or how it is an improvement if it detects fewer instances of the problem. By knowing the why (false positive issues), things click into place.
I can count on zero fingers the number of times I have ever wished I had this.
We do, however, keep daily work logs (each person submits them) so we have a log of everything that everyone worked on. We have Slack history, which is sometimes referred to.
I'm curious what folks find this useful for. What are the scenarios where one has to refer back to an issue from a commit?
By the way, I also have the experience of inheriting a code base where the commit messages were mostly (or just) issue numbers. Guess what I didn't inherit? The issue tracker. The commit messages were useless to me.
Specifically those are work logs (individual daily logs), project logs (logs for larger projects which may consist of a work cell of a few people and several work items), material logs (logs for specific equipment, virtual or otherwise), work in progress notes (notes for ongoing initiatives, including checklists, etc.), etc. They are all text files contained in git repositories that are always available for reference. We can also refer to Slack conversations, but most of our conversations are done live so as to avoid hand-offs, so we must rely on recording of decisions by folks on the team.
We use our work tracking system just to track work -- placeholders for conversation.
My colleague wrote in more detail about what goes into our work and why issue numbers don't even enter our airspace: https://news.ycombinator.com/item?id=38836919
Taking this a bit further you can make sure your branch names have the ticket in them, which you then extract in a git hook (git-prepare-msg) and put as a trailer at the end of the message using ‘git interpret-trailers’
This reduces clutter when looking at a list of messages (eg git log —-oneline) and makes it easier to script things based on the ticket numbers (other git commands can pull out the trailers)
Git commit info needs to live in git. Ticketing systems will always die. The source remains.
You get a new repo in GitHub, and all GitHub activity is lost for REASON.
Tools never persist. I’d even say that ticket numbers in commit messages is harmful since it makes it much easier for the committer to be sloppy and write “Fix bug for JIRA123”. You can say “that’s a people problem”, but with a growing team I can either fix that people problem over and over, or I can ask for no external ticket ids in commit messages
I believe that if teams look hard into the reasons they think that that practice is valuable, they will uncover even greater culture and process problems to address. Once they are addressed, they will no longer need them, and they'll even start to see the harm in them.
Most teams won't do that, however, and I will be dragged out to the town square for even suggesting it's possible (even though our team operates extremely well without this practice or anything resembling it).
It’s a version control system. That includes an explanation as well. The explanation for each revision is integral.
And I don’t think people here really disagree with that. Just that they might prefer to put all that integral information somewhere else—the information (princess) is in another castle, Mario. Why? Why not at least just copy-paste the relevant information into the version control system proper? I see this all the time; people often do the same with GitHub pull requests—paragraphs upon paragraphs in the pull request description and then just a “Merge <convoluted URL>” in the merge commit message!
It’s not that I blame people for this. Maybe Git is just so unergonomic that many would prefer to offload everything into another interface (even Jira).
[1] My tickets will usually have all the history. Maybe a lot of back and forth. The commit message though will just have what was done when all was said and done—no back and forth, just the result. And some of my tickets probably don’t even have a description body since what I ended up doing is just described in the commit message.
99% of the time when I'm looking at commit history, I'm not just generically scanning. I'm usually looking for a particular change, or when something touched a particular file, etc. Even the example given in the linked page isn't really relevant to me, because I'm rarely "quickly scanning" a whole commit log for something in particular - I'd always just use a search feature (in GitHub or some git IDE plugin) for that.