Comment by Willamin

For context, my engineering team is fairly small – no guarantees this scales well for larger organizations. I capture the reasons for decisions on why code was written a particular way or why a particular architecture was decided upon in commit messages. We follow a squash-and-rebase flow for commits, so each PR is ultimately a single commit before merging. During that squash process, I'll update the commit message to sometimes be a few paragraphs long. Later when I'm curious why we made decision in the past, I can use git blame to navigate back until the point where I can find the answer.