As far as I'm concerned, the git history of a project is the root source of truth of why a change was made, at that point in time. External documentation is mostly broad strokes, API references, or out of date. Code comments need to be git blamed anyway to figure out when they were added, and probably don't exist for every little change. Pull requests associated with a given commit give the broad description of "what feature was being implemented or bug was being fixed" for a given change, but a commit message tells me what, specifically, during that work, triggered this particular change. I want to know, for example, that the reason this url gets a random value appended to it is that while implementing a new page to the site it was found that the caching service would serve out-of date versions of some iframe. It never made it out of dev testing, so it never became a full-blown bug, it wasn't the purpose of the feature branch, so it wasn't discussed in the PR. But the commit message of "Add some cache-busting to iframe" (even something that brief), can go wonders to explaining why some oddity exists.
Agree to disagree I guess, but IME, git history is good for low level detail, not for high level information. Git history is a poor source for understanding architecture, code organization, and other aspects of the codebase. More often, git commit messages tell me what changed - not why the change was made or who it impacted or etc.
Reading through git history should be my last resort to figure something out about the codebase. Important knowledge should be written somewhere current (comments, dev docs, etc). If there is a random value being appended to a url, at least a code comment explaining why so I don’t even have to git blame it. Yes, these sources of knowledge take some effort to maintain and sure, if I have a close-knit team on a smaller codebase, then git history could suffice. But larger, long-lived codebases with 100s of contributors over time? There’s just no possible way git history is good enough. I can’t ask new team members to read through thousands of commits to onboard and become proficient in the codebase (and certainly not 5x-10x that number of commits, if we are not squashing/rebasing feature branches into main. Although, maybe now an LLM can explain everything). So I really need good internal/dev documentation anyway, and I want useful git history but don’t care so much about preserving every tiny typo or formatting or other commit from every past feature branch.
Also iirc, with github, when I squash merge via the UI, I get a single squashed commit on main and I can rewrite the commit message with all the detail I like. The PR forever retains the commit history of the feature branch from before the squash, so I still have that feature branch history when I need it later (I rarely do) so I see no reason to clutter up history on main with the yucky feature branch history. And if I tend toward smaller PRs, which is so much nicer for dev velocity anyway, even squashed commits can be granular enough for things like bisect, blame, and so on.
