Great article!

Hopefully with the RNG you're getting the best of both worlds:

- Commit messages describe justification for _changes_. That is, a rationale for going from one state to another state. This discussion generally includes some research on the old state in order to motivate the new state, in addition to information about the new state.

- random.c's code comments and section headers now have lots of up to date information. These describe the present state and are useful as documentation, especially to people hacking on the code, since it's beside the code.

What we don't currently have but something I am working toward is a detached description of the RNG and motivations for various design decisions. This will be useful to researchers and such trying to get a good high level description of how the thing works and motivations for its various components. I expect for this aspect of the documentation to congeal as the RNG's design does as well. But hey, already what's happened in 5.17/5.18 is a pretty big improvement on the status quo.

True, however associating such information with the change itself (and thus _when_ the change was made) makes the historical context pretty clear.

> It's not so great because commit logs are not easy to grep or index

git log --grep works pretty well.

> It's not so great because commit logs are not easy to grep or index.

On the contrary - I find it one of the easiest places to look. I use use all of `git log --grep`, the GitHub search bar, `git gui blame`, `git log -S` (pickaxe) and the VSCode git lens depending on what I'm looking for and what environment I'm using.

The beauty of it is that it's context, context, context.

* Commits (including but not limited to the commit message) provide context for a changed line. I try to provide as many references in my commit messages as I can. This includes references to other commits, or links to bug-trackers or documentation or stack-overflow posts, etc.
* Commits also exist in their own historical context - both in terms of other commits on the branch, what was happening on other branches around the same time, and how and when the commit was merged. The beauty of this is that it happens automatically.
* This context is immediately available in your editor when looking at the code too. With git blame and associated editor integration you can see how the code you're looking at came to be like this. The "why" of some code is immediately accessible. You might argue that this information should be in the comments, and in some cases this true, but you can be a lot more verbose in a git commit message than in a code comment, and with blame *every line* has some message associated with it, with additional context a few clicks away.

> Ideally this kind of explanation should be in nicely structured text files.

I think separate documentation works best for high-level design type documentation that's unlikely to change quickly, and user facing documentation. Less so when things change quickly, or need to be cross-referenced with code.

The beauty of commit messages is that the message is attached to the code, and additional context is captured automatically. With separate documentation you need to refer to the relevant parts of code (and keep those references up to date). You also need to manually include a bunch of context so the future people can understand the documentation - much of which would be included automatically by git. It's also harder to find the relevant documentation from the code, while from any given line the commit message is just a click away. Documentation gets out of date - so do commit messages, but at least with commit messages you can know when it wasn't out of date and you can see exactly the code that it applied to.

Also: if you're writing documentation why not include it in the commit message too? Copy and paste is easy and there's no harm to the duplication. Sometimes I feel like developers are so used to applying DRY to their code that they get carried away and don't ever want to press Ctrl-C, Ctrl-V.

I can understand how people feel differently. A lot of the value of these tools only come if developers take care to make their commits atomic and provide useful information in their commit messages. Worse: you can individually start applying this discipline to a project but you won't start seeing the benefits of doing so for at least several months - it's only really helpful once you've forgotten the context in which the code you're looking at was written.