Hacker News Reader

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

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.

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

Crucially, however, the commit message is not documentation of the code, which would need to be changed and updated. Instead, it is documentation of the change, describing the reason for the change, what the code does to achieve that, and, if relevant, why you chose that solution. It provides necessary context to the already immutable diff and therefore need not be mutable itself.

Sucks when you mess up in your commit message though and don't type the right thing.

If you put docs in a markdown file, you will still be able to see what the markdown said at that time because it will also be in the commit history.

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.

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.

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.

Fossil has something a bit like that.

Can you elaborate how?

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.

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

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

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.

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.

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.

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.

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