4 ms·

I love these commits. Then don't have to be this verbose, but they have to tell a story of why things were done. I can sort of deduce the what from the code its

by drej 7y ago

I love these commits. Then don't have to be this verbose, but they have to tell a story of why things were done. I can sort of deduce the what from the code itself, but the why is sometimes shrouded in mystery. I started with these explanatory git commits a few months ago and they are super useful, even if you're just reading your own commits from some time ago.

tigershark 7y ago
To me they are red flags because it means that very likely who writes this kind of commit messages doesn’t use a proper issue tracking system.
- UK-Al05 7y ago
  It's better to have these in with the source control system, When you change or switch to a different ticketing system, you will bring these with you.
  - tigershark 7y ago
    If you are switching ticketing systems without migrating all the issues you are doing it wrong.
- dijksterhuis 7y ago
  To me its beautiful, because it does what an issue tracking system does not do: it explains everything. Who, why, how, what, when. It is beautiful and simple documentation. Issue tracking typically revolves about the who, what, when - not why it happened, or how it was resolved. This is why I believe that code can never be fully self-documenting. I can't understand why the code exists from reading it. All the floofy contextual stuff is missing, and commits like this help to explain the floofiness.
  - tigershark 7y ago
    I think that you are not using properly the issue tracker. You absolutely need as a bare minimum the why and the reporter of the issue. When you do a blame you can easily see the issue id and open it with 1 click to understand why that code exists and who requested the change.
    - dijksterhuis 7y ago
      But now I have to go find the issue in a completely separate system, rather than just look at the commit message. It’s added complexity, which is something we strive to remove from our code.
- drej 7y ago
  I use these commits, but also use a proper issue tracking system. So I'm not quite sure your comment applies. The reason I'm doing this is: 1. If I'm looking at some code, I want to see its history without having to switch between git(lab|hub) and jira or whatever system I'm using. 2. The issue tracking system doesn't necessarily have some kind of resolve, a summary of what and why happened. It does have a description and a series of comments, but a summary is usually lacking. 3. I believe my commit history will far outlive any issue tracking system I use. So I'm safer putting information into both.
- majkinetor 7y ago
  Totally agree with you. Putting this in the commit is not easily searchable, not universaly accepted and thus not expected, not practical and certainly can't involve discussion easily. This can be replaced with ticket number as most ticketing systems will actually read commit logs for those in order to associate ticket with code. Now, there is that problem with decoupling code and story, but this is technical problem, nothing stops Gitlab and friends storring issues and friends in the repository itself.

by drej 7y ago

tigershark 7y ago

To me they are red flags because it means that very likely who writes this kind of commit messages doesn’t use a proper issue tracking system.

UK-Al05 7y ago
It's better to have these in with the source control system, When you change or switch to a different ticketing system, you will bring these with you.
- tigershark 7y ago
  If you are switching ticketing systems without migrating all the issues you are doing it wrong.
dijksterhuis 7y ago
To me its beautiful, because it does what an issue tracking system does not do: it explains everything. Who, why, how, what, when. It is beautiful and simple documentation. Issue tracking typically revolves about the who, what, when - not why it happened, or how it was resolved. This is why I believe that code can never be fully self-documenting. I can't understand why the code exists from reading it. All the floofy contextual stuff is missing, and commits like this help to explain the floofiness.
- tigershark 7y ago
  I think that you are not using properly the issue tracker. You absolutely need as a bare minimum the why and the reporter of the issue. When you do a blame you can easily see the issue id and open it with 1 click to understand why that code exists and who requested the change.
  - dijksterhuis 7y ago
    But now I have to go find the issue in a completely separate system, rather than just look at the commit message. It’s added complexity, which is something we strive to remove from our code.
drej 7y ago
I use these commits, but also use a proper issue tracking system. So I'm not quite sure your comment applies. The reason I'm doing this is: 1. If I'm looking at some code, I want to see its history without having to switch between git(lab|hub) and jira or whatever system I'm using. 2. The issue tracking system doesn't necessarily have some kind of resolve, a summary of what and why happened. It does have a description and a series of comments, but a summary is usually lacking. 3. I believe my commit history will far outlive any issue tracking system I use. So I'm safer putting information into both.
majkinetor 7y ago
Totally agree with you. Putting this in the commit is not easily searchable, not universaly accepted and thus not expected, not practical and certainly can't involve discussion easily. This can be replaced with ticket number as most ticketing systems will actually read commit logs for those in order to associate ticket with code. Now, there is that problem with decoupling code and story, but this is technical problem, nothing stops Gitlab and friends storring issues and friends in the repository itself.