I sometimes struggle to decide whether to put an explanation in a commit message, in the docs (say in an ADR). I tend to save everything as docs because files are a more “universal” interface, so to speak. They’re in plain sight and harder to miss.
I guess the main advantages of Git history are that it’s (1) uneditable and (2) directly linked to a specific commit.
I usually go for very brief commit messages, one-liners preferentially. I would just write something on the body when I feel it call for more detailed explanation or if the reason isn't too obvious. I started using plain markdown for the "why" for each project, status, changelog, bugs etc. Every change to the notes is a commit and git became an audit trail with all the dated, uneditable record of all the decisions and changes. Markdown files won it for me because they are the first thing I read when I get back to a project and also because of the ease of access to AI tools.
The caveat is that docs can go stale while commit messages can't, it forces you to be extra careful so to be sure that the files are being correctly updated, I took care of that with a simple script that checks all the notes.
zahrevsky · · focus · HN ↗
I guess the main advantages of Git history are that it’s (1) uneditable and (2) directly linked to a specific commit.
tux404 · · focus · HN ↗
The caveat is that docs can go stale while commit messages can't, it forces you to be extra careful so to be sure that the files are being correctly updated, I took care of that with a simple script that checks all the notes.