5 ms·

I think the disadvantage with this style of documentation is you can't really alter the commit message after it's written. (I mean you could obviously with "re

I think the disadvantage with this style of documentation is you can't really alter the commit message after it's written. (I mean you could obviously with "rebase" but are you really going to alter something written one year ago, already merged to "main", and cause a bunch of pain with everyone's feature branch etc.?) Compare that with documentation stored in a .md file, or even a Wiki or even Confluence. My colleague can write something and if I see a way to improve it I can go ahead and do that, and other colleagues can improve on what I've written. In this particular case I suppose the bug is fixed and won't come up again. But I also myself find it tempting to describing the design of a particular component when I commit that component, and that's something I now avoid. What about when that component needs to be changed by a future commit e.g. due to the business requirements changing? Will the commit documentation just describe the differences? Then in order for a new team member to find out how the system works by reading the documentation they've got to read multiple commit messages and "merge" them in their head.

macintux 3y ago
There's no reason this documentation can't be replicated in another context, and for all we know it was.
tyrust 3y ago
I think commit messages are mostly valuable for a future code reader asking "why is this bit like this?" and then looking at blame logs for the answer. As you point out, bigger picture stuff ought to be elsewhere (documentation, tracking bug). Keeping docs in version control and including doc changes with the code changes is a nice way to address your concern.
josephg 3y ago
I really think git made a mistake in conflating the immutable log of what was changed with the (ideally mutable) story of what got merged in. So you see people arguing over squashing commits vs rebasing vs merging. Squashing commits makes the history of commits a better story of features being added. Merging preserves the immutable log of the actual changes made to the code, and rebasing sort of does a bit of both. But, I don't see any reason we can't have our cake and eat it too. We're programming computers after all and we can make them do whatever we like. If I wrote my own git, I think I'd split commits into those two parts. I'd leave the history of changes immutable - probably with some sort of Merkle DAG like Git does. And then have a separate associated data store which stores the commit messages, in a nice sensible, editable log describing the work that actually happened. Let people arrange and rearrange the commit descriptors however they like. If you want, group commits around feature tags, fix typos and make any changes to the messages that you want. But, the whole while the underlying log of diffs ("what actually changed in the code") can remain (gloriously) unaffected.
- zilti 3y ago
  Fossil has something a bit like that.
  - wnoise 3y ago
    Can you elaborate how?
    - zilti 3y ago
      You can add text - essentially a wiki page - to a commit and edit it any time. Additionally, you can also add tech notes, which are wiki-like entries in the timeline alongside commits.
- passivegains 3y ago
  > I really think git made a mistake in conflating the immutable log of what was changed with the (ideally mutable) story of what got merged in. So you see people arguing over squashing commits vs rebasing vs merging. Every team I've been on struggled with this over and over and over. The tools are so hard to use it's tempting to make the version control process facilitate "git log" instead of the other way around, which is just absolutely insane. Obviously my co-workers should learn to use their damn tools like professionals, something something a poor craftsman, but honestly? This time the tools really are to blame.
- deleted 3y ago
  [deleted]
ryanisnan 3y ago
I think the non-editable nature of commit messages is precisely the benefit though. Yes, you can't really modify them post-hoc, but being able to step through a code base's history can be really illuminating.
masklinn 3y ago
> I think the disadvantage with this style of documentation is you can't really alter the commit message after it's written. That is not a disadvantage. The commit is a historical record, if I come back to that commit 3 years later I want to know its purpose in the context it was in, I don’t want a whitewashed history. > Compare that with documentation stored in a .md file, or even a Wiki or even Confluence. My colleague can write something and if I see a way to improve it I can go ahead and do that, and other colleagues can improve on what I've written. That’s like comparing a bicycle and a goose. > But I also myself find it tempting to describing the design of a particular component when I commit that component, and that's something I now avoid. That’s a shame. Knowing the considerations (or lack thereof) and tradeoffs at time of creation are often useful to understand defects, either in the original, or in evolutions, or in changes of use case. > Will the commit documentation just describe the differences? Yeees? > Then in order for a new team member to find out how the system works by reading the documentation they've got to read multiple commit messages and "merge" them in their head. No, for that you maintain a separate “current” documentation, which does not need to cover implementation tradeoffs, or that the original was written under time crunch, or whatever.
- 20after4 3y ago
  I really love documentation that lives in the same repo with the code. My favorite is a .md file for every module, class or component. Some mixture of inline code docs and standalone docs is probably ideal. But docs as markdown that don't require some compile step to build the documentation, and doesn't require opening a browser to view them, is just so much better, IMO, compared to any sort of external docs like a wiki or html on a server somewhere that gets re-generated by a CI job.
- thrdbndndn 3y ago
  > That is not a disadvantage. The commit is a historical record OP's point is that, while commit message is indeed a historical record, documentation isn't (or shouldn't). If you double commit message as documentation, it would cause issues like wrong information confusing or misleading future readers because it's non-editable.
dllthomas 3y ago
> you can't really alter the commit message after it's written You can append with git notes, though on a message that long I expect they're unlikely to be noticed.
goku12 3y ago
Commit messages aren't a replacement for source documentation. The latter contains information relevant to the tree. Commit messages are transient information (historical info as someone put it). For example, an update caused by outdated dependency. Or the tests done to diagnose a bug.
kelnos 3y ago
A commit message isn't documentation that should be updated as things evolve. It's a historical record of a single change. Sure, if you later realize you forgot to put an important detail there, that's a shame. But overall I think it's actually important that they can never change.
tehnub 3y ago
I know this isn't a great solution, but GitHub does let you write comments on individual commits. You could add whatever addendums you want there.
keybored 3y ago
I have seldom run into this being a problem. The context of a commit message is that someone took some minutes to explain what the context of the change is. Using their current understanding. Explain the problem. Lay out the assumptions. Given three paragraphs or so it will help immensely to figure out how or why something you/them thought was the case was in fact wrong when the message was written. That is documentation in itself. And if you make straightforward mistakes like a typo in an issue key in the message and you really care: you can make a note of it on the commit with git notes. > Compare that with documentation stored in a .md file, or even a Wiki or even Confluence. I don’t want to access a remote wiki for every little code context (certainly not Conf.). The code is just right there. Comments/Doc comments/commit messages are mostly enough for that.

macintux 3y ago

There's no reason this documentation can't be replicated in another context, and for all we know it was.

tyrust 3y ago

I think commit messages are mostly valuable for a future code reader asking "why is this bit like this?" and then looking at blame logs for the answer. As you point out, bigger picture stuff ought to be elsewhere (documentation, tracking bug). Keeping docs in version control and including doc changes with the code changes is a nice way to address your concern.

josephg 3y ago

I really think git made a mistake in conflating the immutable log of what was changed with the (ideally mutable) story of what got merged in. So you see people arguing over squashing commits vs rebasing vs merging. Squashing commits makes the history of commits a better story of features being added. Merging preserves the immutable log of the actual changes made to the code, and rebasing sort of does a bit of both. But, I don't see any reason we can't have our cake and eat it too. We're programming computers after all and we can make them do whatever we like. If I wrote my own git, I think I'd split commits into those two parts. I'd leave the history of changes immutable - probably with some sort of Merkle DAG like Git does. And then have a separate associated data store which stores the commit messages, in a nice sensible, editable log describing the work that actually happened. Let people arrange and rearrange the commit descriptors however they like. If you want, group commits around feature tags, fix typos and make any changes to the messages that you want. But, the whole while the underlying log of diffs ("what actually changed in the code") can remain (gloriously) unaffected.

zilti 3y ago
Fossil has something a bit like that.
- wnoise 3y ago
  Can you elaborate how?
  - zilti 3y ago
    You can add text - essentially a wiki page - to a commit and edit it any time. Additionally, you can also add tech notes, which are wiki-like entries in the timeline alongside commits.
passivegains 3y ago
> I really think git made a mistake in conflating the immutable log of what was changed with the (ideally mutable) story of what got merged in. So you see people arguing over squashing commits vs rebasing vs merging. Every team I've been on struggled with this over and over and over. The tools are so hard to use it's tempting to make the version control process facilitate "git log" instead of the other way around, which is just absolutely insane. Obviously my co-workers should learn to use their damn tools like professionals, something something a poor craftsman, but honestly? This time the tools really are to blame.
deleted 3y ago
[deleted]

ryanisnan 3y ago

I think the non-editable nature of commit messages is precisely the benefit though. Yes, you can't really modify them post-hoc, but being able to step through a code base's history can be really illuminating.

masklinn 3y ago

> I think the disadvantage with this style of documentation is you can't really alter the commit message after it's written. That is not a disadvantage. The commit is a historical record, if I come back to that commit 3 years later I want to know its purpose in the context it was in, I don’t want a whitewashed history. > Compare that with documentation stored in a .md file, or even a Wiki or even Confluence. My colleague can write something and if I see a way to improve it I can go ahead and do that, and other colleagues can improve on what I've written. That’s like comparing a bicycle and a goose. > But I also myself find it tempting to describing the design of a particular component when I commit that component, and that's something I now avoid. That’s a shame. Knowing the considerations (or lack thereof) and tradeoffs at time of creation are often useful to understand defects, either in the original, or in evolutions, or in changes of use case. > Will the commit documentation just describe the differences? Yeees? > Then in order for a new team member to find out how the system works by reading the documentation they've got to read multiple commit messages and "merge" them in their head. No, for that you maintain a separate “current” documentation, which does not need to cover implementation tradeoffs, or that the original was written under time crunch, or whatever.

20after4 3y ago
I really love documentation that lives in the same repo with the code. My favorite is a .md file for every module, class or component. Some mixture of inline code docs and standalone docs is probably ideal. But docs as markdown that don't require some compile step to build the documentation, and doesn't require opening a browser to view them, is just so much better, IMO, compared to any sort of external docs like a wiki or html on a server somewhere that gets re-generated by a CI job.
thrdbndndn 3y ago
> That is not a disadvantage. The commit is a historical record OP's point is that, while commit message is indeed a historical record, documentation isn't (or shouldn't). If you double commit message as documentation, it would cause issues like wrong information confusing or misleading future readers because it's non-editable.

dllthomas 3y ago

> you can't really alter the commit message after it's written You can append with git notes, though on a message that long I expect they're unlikely to be noticed.

goku12 3y ago

Commit messages aren't a replacement for source documentation. The latter contains information relevant to the tree. Commit messages are transient information (historical info as someone put it). For example, an update caused by outdated dependency. Or the tests done to diagnose a bug.

kelnos 3y ago

A commit message isn't documentation that should be updated as things evolve. It's a historical record of a single change. Sure, if you later realize you forgot to put an important detail there, that's a shame. But overall I think it's actually important that they can never change.

tehnub 3y ago

I know this isn't a great solution, but GitHub does let you write comments on individual commits. You could add whatever addendums you want there.

keybored 3y ago

I have seldom run into this being a problem. The context of a commit message is that someone took some minutes to explain what the context of the change is. Using their current understanding. Explain the problem. Lay out the assumptions. Given three paragraphs or so it will help immensely to figure out how or why something you/them thought was the case was in fact wrong when the message was written. That is documentation in itself. And if you make straightforward mistakes like a typo in an issue key in the message and you really care: you can make a note of it on the commit with git notes. > Compare that with documentation stored in a .md file, or even a Wiki or even Confluence. I don’t want to access a remote wiki for every little code context (certainly not Conf.). The code is just right there. Comments/Doc comments/commit messages are mostly enough for that.