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.
There's an additional aspect: whoever ends up reading the messages later might not even be aware that there is more information somewhere else.
That's why I prefer to keep any important information as close as possible, either in the commit message or as a comment in the source code, to make sure it's unmissable to anyone working on it later.
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.
In my projects WHY always goes to ADR because every decision should be well documented, not only as a comment but with arguments. Moreover a decision may change and the change should be documented too. A published commit message is unchangeable. In one of my projects I have 170 commits and 85 ADRs where one is accepted temporary and one superseded by another.
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.
mopsi · · focus · HN ↗
That's why I prefer to keep any important information as close as possible, either in the commit message or as a comment in the source code, to make sure it's unmissable to anyone working on it later.
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.
beybol · · focus · HN ↗