This commit adds internals documentation that starts to document the
files and semantics of the .hg/ directory.
A lot of this functionality is currently only documented via code
(that doesn't count as documentation!). And the semantics are often wonky
enough that it warrants documentation.
I set out attempting to document the file layout for .hg/. Along the
way, I realized I also needed to document the semantics of lock files,
the path encoding of the revlog store, and how transactions work.
The documentation is missing critical information, such as a thorough
accounting of all the random files in .hg/ and .hg/store and their
formats. But perfect is the enemy of good. And some documentation
seems strictly better than no documentation.
The transaction documentation could definitely be better. However, the
transaction code and transaction semantics are a hot mess and it is
incredibly difficult to read and reason about. I think the only reasonable
way we document and validate the documentation of transactions is by
refactoring the code to actually be readable and document what we learn
along the way.
I started writing these docs several months ago, before the shared hgrc
work started. So the documentation is missing details about this feature
as well. But that's an experimental feature. Hopefully we can add details
of this feature to these docs before that feature stabilizes.