I consider the version control history to be part of the code.

I put docs into the source tree (sometimes in the form of comments; sometimes in dedicated doc files) for things that are suited to live next to the code, but often my commit messages contain more discussion of what used to be and why I chose a certain implementation approach.

I generally think that documentation in code should describe what the code does and why, and commit messages should describe why critical choices were made and how the new approach differs from previous behavior.

This assumes a good version control system that follows history across renames and moves etc., of course.

Code tends to live longer than the VCS that stores it. I've seen more than one VCS migration that ended up losing a lot of the history of how things got to be where they are today.

Look at all the long lived open source software around, be it Linux itself, gcc or KDE. They all have gone to great lengths to preserve all commit history across all migrations of VCS or code hosting.

(Sometimes absurdly so, as in the case of gcc, where flamewars have been fought to preserve commits that were broken to begin with.)

That is important, and that much care for the code probably helped them survive for so long. Botched VCS migrations is not something that should be accepted anywhere.

I guess I’m an optimist on that front. I’ve lost history from CVS and SCCS, but not from SVN, Perforce, Git or Mercurial, including a number of Git module extractions. I think that history-losing version control migrations are a thing of the past.

Check out a 'zip' file to cross port to a system that does not support your VCS of choice (many embedded systems, for instance) and poof half your docs are gone... VCS should store the code, commit messages should aid in bi-secting but should not explain too much other than to clearly document what was changed in that commit with reference to a particular ticket if available. That way you keep the meta stuff in one place and all the action where the code itself lives, and where you are most likely to need it.

I'm a big fan of literate programming, and VCS is not an integral part of that.

Where do you encounter such embedded systems where you then do work on the code on said system?

In my niche of embedded work, the "host" machine stays the main interface to work with code almost always (and in the exceptions the "embedded" system is typically PC-grade hardware running Linux)

Particularly if there's been a big refactor of the directory layout. The easiest way to do that is move the code and merge it, along with all the fixups needed, as a giant delete & add operation, and git won't necessarily figure it out.

With care, it's possible even to merge different git repos into a single repo while preserving history. But it takes care; it's not a pit of success.