[V-2]

These two aren't mutually exclusive. Tickets, however, have lower long-term survivability (in my experience). Outsourcing, migrations, there are many scenarios in which the original tickets become inaccessible over time - and some codebases do last for years and years. Meanwhile the repository content (and thus the complete version history) usually survives as-is.

[lostcolony]

I didn't mean to imply they were mutually exclusive; just that in terms of "most high-impact documentation you can write", I find ensuring I link the ticket higher than making sure I have a thoughtful commit message, for the reasons listed.

Fair that it can disappear eventually if you change ticket trackers or whatever; that's a risk of changing ticket trackers. Hopefully you maintain both for a bit, and once you're six months out or whatever and retire the old, you don't need as much context since things have moved on (and there's a generational effect in tickets akin to that in garbage collection; you tend to need recent things more often than old things, and the older, the less likely you are to need it).

But just in terms of "what would I rather have", a link to the ticket every time. And in terms of "what am I more likely to provide", a link to the ticket every time as well (since all the communication on the ticket came about out of need; writing a thorough commit message is out of preparation, and I, and everyone else, am WAY better at consistently doing things that I need to do than preparing for possible future things)

[fatnoah]

> But just in terms of "what would I rather have", a link to the ticket every time

In practice over the past 20+ years, I've had to rely on commit messages far more than tickets, but a well-written ticket is defnitely awesome to have. When I ran Engineering for a startup, one of the things we invested a lot of time in was making sure commits had good messages, tickets had good writeups, and the two were linked. We required a pull request to close a ticket, and our CI system would automatically append a link to the ticket to the PR when it was merged. It was such a level of awesomesauce.

[democracy]

Just out of curiosity - how many different CVS did you use in the past 20+ years?

I went through 5 different CVSs and the history was gone forever in each migration - but actually JIRA is still the same after 16 years )))

[fatnoah]

Obviously my experience is my own, but in many cases it was the ticket system that changed vs. the version control system, which is why history wasn't always there. A lot of my early experience was at startups and I think I saw a version control migration only happen once (VSS to Git). I've even seen a couple places that didn't even have a ticket system. Unsurprisingly, those no longer exist.

In any case, I think the "correct" answer is proper commit messages AND solid issue tracking. My preference for commit when looking in the past was more around trying to understand particular changes to specific files or lines of code, which are more easily navigated in source control. A good commit message helps narrow down things when there is a long history, but a link in that message to the actual ticket would be a dream since that would likely have the larger context.

All that said, I have spent some time at a FAANG and neither commit messages nor tickets were useful at all there. Commit messages were usually along the lines of "fix a bug" or "add a feature" and the tickets rarely had more detail than "fix X" or "add Y". That was more of a symptom of the "go forward" culture there. Little time was spent making it easier for the next person since that wasn't really rewarded in the performance process.

[wruza]

The commit message idea always felt a little strange/off to me. It's a string that you can't (generally) fix/extend later for those who may seek this information. Also nobody except the committer can write them. (Imagine an explicit @docsguy role for documenting commits along with writing ticket-based documentation.)

What if VCSs used a single file or a folder, like .gitcommits, where anyone could append any sort of info in the same commit, so it could be a part of it. Then, when you commit a feature, you add to this file(-s):

  @@ @@
  +---
  +added websocket support to the server
  +  /ws - main socket
  +  /ws-events - events socket

And few commits later you decide to extend it, editing the same record:

  @@ @@
  +---
  +added json-rpc over websockets
  +  /ws-json-rpc

And VCS would then extract these records at `git log`:

  ...
  4509812 added websocket support to the server
  0732691 <no .gitcommits message>
  8712389 added json-rpc over websockets

Few commits later @docsguy expand on json-rpc:

  @@ @@
   ---
  -added json-rpc over websockets
  +added lifetime-related json-rpc over websockets
  +task: ./tasks/1873.md
  +supports 'start' and 'stop' methods: ./doc/ws-lifetime.md
   /ws-json-rpc
  @@ @@
  +---
  +enhanced commit descriptions

  A  tasks/1873.md
  A  doc/ws-lifetime.md

  4509812 added websocket support to the server
  0732691 <no .gitcommits message>
  8712389 added lifetime-related json-rpc over websockets
  6034007 enhanced commit descriptions

Full commit messages would then be just diffs. Also, one could write a commit message gradually, with the sources they are modifying. Or write two commit messages at once (because we all do commit two+ changes sometimes):

  @@ @@
  +---
  +refactored foo bar heavily, @docsguy please expand
  +---
  +fixed a bug in baz, didn't care to backport

  ...
  0923423 refactored foo bar heavily, @docsguy please expand
          fixed a bug in baz, didn't care to backport

[nitrogen]

I've never used git-notes, but it sounds like this is what you are describing: https://git-scm.com/docs/git-notes

[wruza]

While looking similar, they are something different, not versioned in the same way (alongside) as content, or editing a commit message.