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.
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.
beybol · · focus · HN ↗