Hacker News Reader

Comment by silisili | Hacker News Reader

As one on the 'supports this decision' side, thanks for taking time from your day to give us the history.

It would be really nice if such context existed elsewhere other than a rather ephemeral forum. It would be awesome to somehow have annotations around certain decisions in a centralized place, though I have no idea how to do that cleanly.

View on HN

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.

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

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

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.

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

Reply on news.ycombinator.com