3 ms·

Should this go into a commit message, instead of an issue/ticket?

by Chris2048 7y ago

tomstuart 7y ago
Yes, because it lives with the code.
adamlett 7y ago
I say yes. I like to keep information about the code as close to the code as possible. Issue trackers come and go, and even if you keep the same issue tracker around, how are you going to relate the change in the code to the particular issue down the road? FWIW, I also prefer READMEs to Wikis.
- Crinus 7y ago
  > Issue trackers come and go Unless you use Fossil :-P. Or for git/hg/svn/cvs/Folder - Copy(43), one of those ticket trackers that work with files inside the repository itself.
- crdoconnor 7y ago
  As close to the code as possible means a code comment, not a commit message.
- Chris2048 7y ago
  > Issue trackers come and go What do you mean? Just put an issue ID in the code and/or commit.
  - adamlett 7y ago
    Let’s hope the SaaS issue tracker you’re currently using never goes out of business or changes the product in a way that makes it worse for you. Or, if you host your own, that it keeps you satisfied in perpetuity. Referring to the issue ID in the commit message is a fine practice in addition to writing good, comprehensive commit messages. Commit messages that consists only of an issue ID are – in my experience – utterly frustrating to deal with. They tell you nothing more than this change is somehow related to this or that bug or feature, but not how or why.
    - Chris2048 7y ago
      > Let’s hope the SaaS issue tracker So the solution to a unreliable issue tracking solution is dumping that responsibility on your VCS? Why not fix the concerns you have with your issue tracker? > writing good, comprehensive commit messages. Commit messages that consists only of an issue ID Who said anything about only including a tracker id? The issue here is the extra verbosity in the commit message. What will the tracker tickets contain that isn't in your "comprehensive" commit message?
      - adamlett 7y ago
        * So the solution to a unreliable issue tracking solution is dumping that responsibility on your VCS? Why not fix the concerns you have with your issue tracker?* … Or, and hear me out, how about not worrying about that, and just use your VCS to accomplish something it’s imminently well suited for? Also, how do you propose I solve the issue of the issue tracking service maybe going out of business or that of a more compelling product coming along? To me, the primary purpose of an issue tracker is to collaborate on and track work in progress, and that’s what I use them for. I don’t find that they are particularly valuable as historical records of the source code.
  - snorremd 7y ago
    But then you switch out your issue tracker service from something like Jira to something else, and suddenly that ID or URL means squat. A git repository can easily be pushed to any git based service be it GitHub, GitLab, Gitea, or something else, and the commit log and commit hashes stays the same. Porting Jira issues to a different system would probably not preserve those IDs that you entered into your commit message. By all means, refer to your issue tracker in commit messages, but be aware that those references may not be valid in a few years.
    - Chris2048 7y ago
      Just put the old ID in the new ticket, then search. Or put commit hashes into the ticket and search by that. > A git repository .. and the commit log and commit hashes stays the same If issue trackers are so transient and flaky, and VCSs are so solid, then back up your old issue tracker and put it in git. What if your issue tracker stays, but you VCS changes?
Sharparam 7y ago
Since this is describing the commit and what was done and why, the commit seems like a better place. In tools like GitHub, if you make a PR with this commit, it will also automatically put the text in the PR description. I would much prefer this at work over what I usually see with inconsistent commit message styles and not explaining properly what was done, and not following the recommended max length per line.
- Chris2048 7y ago
  but "why" includes lots of detail about the steps they went through. Why can't "there was utf-8/non-ascii whitespace in the file" Cover all of that? Why detail all the steps to reproduce?
shakna 7y ago
The commit message still logs in the usual way, but it carries the whole set of information with it, in a way that a centralised ticket system doesn't. When a developer is looking at logs for solving some problem, they can easily review the rationale for changes. I'd much prefer the log explaining everything, rather than having to look to a ticket that may no longer exist.
- Chris2048 7y ago
  > in a way that a centralised ticket system doesn't Why doesn't it? Are closed issues not searchable? It seems to me you doubt the ticket retention, but instead of fixing that, use commits to store issues instead. How do you provide comments or updates on an issue "relevant to the commit" without arbitrary commits?
  - shakna 7y ago
    > Why doesn't it? Are closed issues not searchable? Everywhere I have ever worked has changed ticket systems at one point, and even when they are transferred, the transfer is "lossy". Heck, just moving from one JIRA version to another can be "lossy". > How do you provide comments or updates on an issue "relevant to the commit" without arbitrary commits? In the ticket system. I was not advocating that a ticket system is pointless, because they are very useful. But a decent commit message about why a change is necessary, especially when it may not be straight forward, can save you plenty of development time further down the line.
    - Chris2048 7y ago
      I have mixed feelings about JIRA, but if you move to a centralised ticket system you have to plan migration. If you really need to, put more detailed notes into an "Issues" file for commits/minor releases, and clear it on every major release. IMO the given example is more verbose that needed. It should give enough information about what and why a fix is done, but no more.
torgard 7y ago
If you put it in a pull request, that'll just put it in the merge commit instead. I'd prefer it being on the commit itself.
Dzugaru 7y ago
A great question! I’m still wondering why we all mostly use separate tools for tickets and version control (and knowledge base, and collaboration, and management/hiring, the list goes on), given we already know a lot about software development.
- jimws 7y ago
  Fossil - https://www.fossil-scm.org/ https://www.fossil-scm.org/ Code, commit logs, tickets, and project management are all part of the same repo with Fossil.
- Chris2048 7y ago
  I think it's more than that. Sometimes I feel there is a disconnect between code history and repo contents e.g the current repo often contains a folder with the entire history of migrations, changelog etc
jimws 7y ago
Absolutely yes. As a developer I can: git log | grep <error message> git show <commit id> I don't have to go looking for an issue tracker and figuring out how to search it effectively.
- Chris2048 7y ago
  As a developer, you can also search the issue tracker, and don't have to go looking for commit in the VCS and figuring out how to search it effectively.
the_duke 7y ago
This is a big discussion. In a professional setting, companies usually want this information to live in the issue tracker. Mainly to provide insight to managers/other teams without looking at commit messages. But it removes the information from the code: you now need to look at the issue tracker to make sense of changes, eg when looking at the history of a file, or with git-blame. I'd argue that all relevant information that affects the code and architecture of the specific repo should live in commits. They should not only tell you what was changed, but also why; and provide enough context to understand the change in the scope of the repo. All information that is not directly tied to the code, eg cross-repo/product/etc concerns can go in the issue tracker. Of course this only works well with a `git commit --fixup` and squash + rebase / squash + merge workflow. And with monorepos it also becomes a tooling problem.
- Chris2048 7y ago
  > you now need to look at the issue tracker to make sense of changes Not really, the commit message can be informative without being this verbose. > you now need to look at the issue tracker Doesn't seem like a bad thing to me. Issue trackers are designed to search through.
tigershark 7y ago
In my opinion absolutely no. It should go in a Jira issue and the commit should have the Jira id in the message. In this way when blaming you are just one click away to the full issue description, with properly formatted text and screenshot if needed. It will also be visible to all the team in the Jira board and they don’t have to click on the specific commit to notice that problem.

Should this go into a commit message, instead of an issue/ticket?

Yes, because it lives with the code.

I say yes. I like to keep information about the code as close to the code as possible. Issue trackers come and go, and even if you keep the same issue tracker around, how are you going to relate the change in the code to the particular issue down the road? FWIW, I also prefer READMEs to Wikis.

Crinus 7y ago
> Issue trackers come and go Unless you use Fossil :-P. Or for git/hg/svn/cvs/Folder - Copy(43), one of those ticket trackers that work with files inside the repository itself.
crdoconnor 7y ago
As close to the code as possible means a code comment, not a commit message.
Chris2048 7y ago
> Issue trackers come and go What do you mean? Just put an issue ID in the code and/or commit.
- adamlett 7y ago
  Let’s hope the SaaS issue tracker you’re currently using never goes out of business or changes the product in a way that makes it worse for you. Or, if you host your own, that it keeps you satisfied in perpetuity. Referring to the issue ID in the commit message is a fine practice in addition to writing good, comprehensive commit messages. Commit messages that consists only of an issue ID are – in my experience – utterly frustrating to deal with. They tell you nothing more than this change is somehow related to this or that bug or feature, but not how or why.
  - Chris2048 7y ago
    > Let’s hope the SaaS issue tracker So the solution to a unreliable issue tracking solution is dumping that responsibility on your VCS? Why not fix the concerns you have with your issue tracker? > writing good, comprehensive commit messages. Commit messages that consists only of an issue ID Who said anything about only including a tracker id? The issue here is the extra verbosity in the commit message. What will the tracker tickets contain that isn't in your "comprehensive" commit message?
    - adamlett 7y ago
      * So the solution to a unreliable issue tracking solution is dumping that responsibility on your VCS? Why not fix the concerns you have with your issue tracker?* … Or, and hear me out, how about not worrying about that, and just use your VCS to accomplish something it’s imminently well suited for? Also, how do you propose I solve the issue of the issue tracking service maybe going out of business or that of a more compelling product coming along? To me, the primary purpose of an issue tracker is to collaborate on and track work in progress, and that’s what I use them for. I don’t find that they are particularly valuable as historical records of the source code.
- snorremd 7y ago
  But then you switch out your issue tracker service from something like Jira to something else, and suddenly that ID or URL means squat. A git repository can easily be pushed to any git based service be it GitHub, GitLab, Gitea, or something else, and the commit log and commit hashes stays the same. Porting Jira issues to a different system would probably not preserve those IDs that you entered into your commit message. By all means, refer to your issue tracker in commit messages, but be aware that those references may not be valid in a few years.
  - Chris2048 7y ago
    Just put the old ID in the new ticket, then search. Or put commit hashes into the ticket and search by that. > A git repository .. and the commit log and commit hashes stays the same If issue trackers are so transient and flaky, and VCSs are so solid, then back up your old issue tracker and put it in git. What if your issue tracker stays, but you VCS changes?

Sharparam 7y ago

Since this is describing the commit and what was done and why, the commit seems like a better place. In tools like GitHub, if you make a PR with this commit, it will also automatically put the text in the PR description. I would much prefer this at work over what I usually see with inconsistent commit message styles and not explaining properly what was done, and not following the recommended max length per line.

Chris2048 7y ago
but "why" includes lots of detail about the steps they went through. Why can't "there was utf-8/non-ascii whitespace in the file" Cover all of that? Why detail all the steps to reproduce?

shakna 7y ago

The commit message still logs in the usual way, but it carries the whole set of information with it, in a way that a centralised ticket system doesn't. When a developer is looking at logs for solving some problem, they can easily review the rationale for changes. I'd much prefer the log explaining everything, rather than having to look to a ticket that may no longer exist.

Chris2048 7y ago
> in a way that a centralised ticket system doesn't Why doesn't it? Are closed issues not searchable? It seems to me you doubt the ticket retention, but instead of fixing that, use commits to store issues instead. How do you provide comments or updates on an issue "relevant to the commit" without arbitrary commits?
- shakna 7y ago
  > Why doesn't it? Are closed issues not searchable? Everywhere I have ever worked has changed ticket systems at one point, and even when they are transferred, the transfer is "lossy". Heck, just moving from one JIRA version to another can be "lossy". > How do you provide comments or updates on an issue "relevant to the commit" without arbitrary commits? In the ticket system. I was not advocating that a ticket system is pointless, because they are very useful. But a decent commit message about why a change is necessary, especially when it may not be straight forward, can save you plenty of development time further down the line.
  - Chris2048 7y ago
    I have mixed feelings about JIRA, but if you move to a centralised ticket system you have to plan migration. If you really need to, put more detailed notes into an "Issues" file for commits/minor releases, and clear it on every major release. IMO the given example is more verbose that needed. It should give enough information about what and why a fix is done, but no more.

torgard 7y ago

If you put it in a pull request, that'll just put it in the merge commit instead. I'd prefer it being on the commit itself.

Dzugaru 7y ago

A great question! I’m still wondering why we all mostly use separate tools for tickets and version control (and knowledge base, and collaboration, and management/hiring, the list goes on), given we already know a lot about software development.

jimws 7y ago
Fossil - https://www.fossil-scm.org/ https://www.fossil-scm.org/ Code, commit logs, tickets, and project management are all part of the same repo with Fossil.
Chris2048 7y ago
I think it's more than that. Sometimes I feel there is a disconnect between code history and repo contents e.g the current repo often contains a folder with the entire history of migrations, changelog etc

jimws 7y ago

Absolutely yes. As a developer I can: git log | grep <error message> git show <commit id> I don't have to go looking for an issue tracker and figuring out how to search it effectively.

Chris2048 7y ago
As a developer, you can also search the issue tracker, and don't have to go looking for commit in the VCS and figuring out how to search it effectively.

the_duke 7y ago

This is a big discussion. In a professional setting, companies usually want this information to live in the issue tracker. Mainly to provide insight to managers/other teams without looking at commit messages. But it removes the information from the code: you now need to look at the issue tracker to make sense of changes, eg when looking at the history of a file, or with git-blame. I'd argue that all relevant information that affects the code and architecture of the specific repo should live in commits. They should not only tell you what was changed, but also why; and provide enough context to understand the change in the scope of the repo. All information that is not directly tied to the code, eg cross-repo/product/etc concerns can go in the issue tracker. Of course this only works well with a `git commit --fixup` and squash + rebase / squash + merge workflow. And with monorepos it also becomes a tooling problem.

Chris2048 7y ago
> you now need to look at the issue tracker to make sense of changes Not really, the commit message can be informative without being this verbose. > you now need to look at the issue tracker Doesn't seem like a bad thing to me. Issue trackers are designed to search through.

tigershark 7y ago

In my opinion absolutely no. It should go in a Jira issue and the commit should have the Jira id in the message. In this way when blaming you are just one click away to the full issue description, with properly formatted text and screenshot if needed. It will also be visible to all the team in the Jira board and they don’t have to click on the specific commit to notice that problem.