3 ms·

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 elsew

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.

pwdisswordfish9 4y ago
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.
- silisili 4y ago
  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.
  - wongarsu 4y ago
    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 https://news.ycombinator.com/item?id=32353500
- cerved 4y ago
  just write a note instead
satyanash 4y ago
use git notes for attaching information to important commits, after the fact, without altering their SHA
- mbakke 4y ago
  How do you share notes with other users?
  - yawaramin 4y ago
    Notes are just objects stored in the git repo. They are distributed along with all the other objects.
    - mbakke 4y ago
      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.
nicolast 4y ago
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.
aae42 4y ago
Let me introduce you to [ADRs](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions https://cognitect.com/blog/2011/11/15/documenting-architectu...)
joatmon-snoo 4y ago
Filed https://github.com/golang/go/issues/57530 https://github.com/golang/go/issues/57530.

pwdisswordfish9 4y ago

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.

silisili 4y ago
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.
- wongarsu 4y ago
  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 https://news.ycombinator.com/item?id=32353500
cerved 4y ago
just write a note instead

satyanash 4y ago

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

mbakke 4y ago
How do you share notes with other users?
- yawaramin 4y ago
  Notes are just objects stored in the git repo. They are distributed along with all the other objects.
  - mbakke 4y ago
    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.

nicolast 4y ago

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.

aae42 4y ago

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

joatmon-snoo 4y ago

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