To "alter" a commit message after it has already been widely disseminated, branch from the offending commit, make a new commit with a message that contains the relevant info, switch back to mainline, and then merge that branch.

That would be an awesome start.

It would also be really nice to have a 'book' of sorts of this type of lore. Though admittedly, it would probably be hard to remember what to even include without stories like this.

The Arc42 documentation template hat was one of the 12 sections dedicated to "important, expensive or critical design descisions". It makes a pretty good structure for big-picture documetation in a "book" next to the code.

[1] https://news.ycombinator.com/item?id=32353500

just write a note instead

use git notes for attaching information to important commits, after the fact, without altering their SHA

How do you share notes with other users?

Notes are just objects stored in the git repo. They are distributed along with all the other objects.

You had me worried there for a bit, but notes are not distributed by default.

For the curious, you can push/fetch

  refs/notes/*

...to share notes.

For this kind of decisions, why not simply keep notes as comments in the code? These can easily be added later, even 14+ years after the code was written. Then, when someone dives into the codebase to figure out why something was done this or that way, the answer is right there. No need to dive into (and scavenge, sometimes) VCS history.

Let me introduce you to [ADRs](https://cognitect.com/blog/2011/11/15/documenting-architectu...)

Filed https://github.com/golang/go/issues/57530.