4 ms·

TBH, at least at every company I've worked at recently, the style of the commits is more or less irrelevant to me save for one very important piece: The commit

TBH, at least at every company I've worked at recently, the style of the commits is more or less irrelevant to me save for one very important piece: The commit starts with the ID of the ticket for the code change (or some placeholder for very small commits where a ticket wasn't necessary, e.g. [no-tix]). The biggest benefit of this is that these commits can then be automatically linked to the ticket which often has a lot more detail and conversation. 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.

avgcorrection 3y ago
I agree that the ticket id should go somewhere in the commit message. Certainly if things like pull requests are tied to tickets. However I get a little concerned that such sentiments are so popular here. Because the ticket id is a nice contextual link. But the commit message should be self-contained with regards to the change.[1] 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.
kelnos 3y ago
To me, the ticket id is extra info and goes at the end of the message body, not in the title at all. 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.
- The_Colonel 3y ago
  > The commit history should be the primary source of truth for what changes have happened. 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.
  - avgcorrection 3y ago
    > It's just super impractical. 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.
    - The_Colonel 3y ago
      My team uses git to develop in separate branches and merge into master once ready. It's quite practical for that purpose. We don't use it for documentation of changes made, we have better tools for that.
      - avgcorrection 3y ago
geraldwhen 3y ago
Wait until corporate drops jira, or migrates prem to cloud or vice versa with data loss, or revokes your access to an old project id the app was run on. Git commit info needs to live in git. Ticketing systems will always die. The source remains.
formerly_proven 3y ago
This tends to become useless after a few years because of tool or software migrations, changes in JIRA/whatever structure, ticket retention policies etc.
- interbased 3y ago
  I've been using the issue key prefix for years now and I never thought about this aspect. If a board gets archived, for example, those issues need to remain available. You're also just tied to that tool like you mentioned. It would probably be good practice then to also include a blurb in the PR description so that never gets lost.
  - hmeh 3y ago
    Point of order, PRs get lost too. Git repositories can be moved from GitHub to GitLab, or tar'd up and sent in an email when a project gets handed off to its new maintainers. We try to keep things that matter in text files in repositories. We will always own those. Tools are just tools for transient activities (work items in our task tracker are just placeholders for conversations).
    - geraldwhen 3y ago
      Or even the most mundane: corporate mandates that your project name change because of RULE with new access requirements. 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
      - hmeh 3y ago
        Very much agree. I've seen it leak into conversation in slack too... "Hey, I have a question about JIRA123, should we use blue for the button?". There's no greater way to tell someone you don't care about their time than presuming to force them to look up work items every time you want to refer to something. 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).
imron 3y ago
> The commit starts with the ID of the ticket for the code change (or some placeholder for very small commits where a ticket wasn't necessary, e.g. [no-tix]). 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)
lucb1e 3y ago
> 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, 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 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.
hmeh 3y ago
Author here. We have actually managed to use the same task tracking tool for the three years our project has been running: Linear. We don't do pull requests, and we don't put our work item number in our commit messages. 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.
- pseudalopex 3y ago
  https://news.ycombinator.com/item?id=38832525 https://news.ycombinator.com/item?id=38832525 https://news.ycombinator.com/item?id=38836183 https://news.ycombinator.com/item?id=38836183
  - hmeh 3y ago
    Got it, thank you for the links. As I suspected, we just don't have these problems. Rather, we have other things that cover these needs when they arise that we have full ownership of (i.e., it won't matter if our issue tracker is replaced). 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 https://news.ycombinator.com/item?id=38836919
- AceyMan 3y ago
dev_tty01 3y ago
I prefer to go the other way. Put the commit ID(s) and/or links in the ticketing system as part of ticket comments. Now if the ticket system changes or is exported to another system the commit ID(s) will still be in the record. They are much less likely to change plus you can have multiple commits for an issue.

avgcorrection 3y ago

I agree that the ticket id should go somewhere in the commit message. Certainly if things like pull requests are tied to tickets. However I get a little concerned that such sentiments are so popular here. Because the ticket id is a nice contextual link. But the commit message should be self-contained with regards to the change.[1] 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.

kelnos 3y ago

To me, the ticket id is extra info and goes at the end of the message body, not in the title at all. 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.

The_Colonel 3y ago
> The commit history should be the primary source of truth for what changes have happened. 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.
- avgcorrection 3y ago
  > It's just super impractical. 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.
  - The_Colonel 3y ago
    My team uses git to develop in separate branches and merge into master once ready. It's quite practical for that purpose. We don't use it for documentation of changes made, we have better tools for that.
    - avgcorrection 3y ago

geraldwhen 3y ago

Wait until corporate drops jira, or migrates prem to cloud or vice versa with data loss, or revokes your access to an old project id the app was run on. Git commit info needs to live in git. Ticketing systems will always die. The source remains.

formerly_proven 3y ago

This tends to become useless after a few years because of tool or software migrations, changes in JIRA/whatever structure, ticket retention policies etc.

interbased 3y ago
I've been using the issue key prefix for years now and I never thought about this aspect. If a board gets archived, for example, those issues need to remain available. You're also just tied to that tool like you mentioned. It would probably be good practice then to also include a blurb in the PR description so that never gets lost.
- hmeh 3y ago
  Point of order, PRs get lost too. Git repositories can be moved from GitHub to GitLab, or tar'd up and sent in an email when a project gets handed off to its new maintainers. We try to keep things that matter in text files in repositories. We will always own those. Tools are just tools for transient activities (work items in our task tracker are just placeholders for conversations).
  - geraldwhen 3y ago
    Or even the most mundane: corporate mandates that your project name change because of RULE with new access requirements. 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
    - hmeh 3y ago
      Very much agree. I've seen it leak into conversation in slack too... "Hey, I have a question about JIRA123, should we use blue for the button?". There's no greater way to tell someone you don't care about their time than presuming to force them to look up work items every time you want to refer to something. 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).

imron 3y ago

> The commit starts with the ID of the ticket for the code change (or some placeholder for very small commits where a ticket wasn't necessary, e.g. [no-tix]). 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)

lucb1e 3y ago

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

hmeh 3y ago

Author here. We have actually managed to use the same task tracking tool for the three years our project has been running: Linear. We don't do pull requests, and we don't put our work item number in our commit messages. 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.

pseudalopex 3y ago
https://news.ycombinator.com/item?id=38832525 https://news.ycombinator.com/item?id=38832525 https://news.ycombinator.com/item?id=38836183 https://news.ycombinator.com/item?id=38836183
- hmeh 3y ago
  Got it, thank you for the links. As I suspected, we just don't have these problems. Rather, we have other things that cover these needs when they arise that we have full ownership of (i.e., it won't matter if our issue tracker is replaced). 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 https://news.ycombinator.com/item?id=38836919
AceyMan 3y ago

dev_tty01 3y ago

I prefer to go the other way. Put the commit ID(s) and/or links in the ticketing system as part of ticket comments. Now if the ticket system changes or is exported to another system the commit ID(s) will still be in the record. They are much less likely to change plus you can have multiple commits for an issue.