On Sat, Jan 07, 2023 at 05:01:54AM +0000, Allison Henderson wrote: <snip> There was one part of your reply that I wanted to handle separately: > Something that I've noticed in my training sessions is that often > times, less is more. People really only absorb so much over a > particular duration of time, so sometimes having too much detail in the > context is not as helpful as you might think. I'm very worried about this ^^^ exact problem making it more difficult to merge online fsck. As the online fsck patchset grew and grew and grew, I decided that it was absolutely necessary to write a design document to condense the information from 1200 patches, for this is the diffstat for the code changes themselves: 225 files changed, 41244 insertions(+), 4388 deletions(-) 205 files changed, 16802 insertions(+), 3405 deletions(-) 438 files changed, 20123 insertions(+), 446 deletions(-) That's 78169 insertions and 8239 deletions, or about ~70k new LOC, and that doesn't include the scrub code that's already upstream (~60000). It's wild that online fsck is larger than the filesystem. You might recall that I sent it out for review twice last year, and the feedback I got from the experienced folk was that I needed to write in much more detail about the design -- specifically, what I was doing with the fs hooks, and all the data structures that I was layering atop tmpfs files to support rebuilds. Before I even got to /that/ point, the design documentation had reached 4500 lines (or 90 pages) long, at which point I decided that it was necessary to write a summary to condense the 4500 lines down to a single chapter. Hence part 1 about what is a filesystem check. It's supposed to introduce the very very broad concepts to a reader before they dive into successively higher levels of detail in the later parts. My guess is that the audience for the code deluges and this design doc fall into roughly these categories: * Experienced people who have been around XFS and Linux for a very long time. These people, I think, would benefit from scanning parts 2 and 3 as a refresher. Then they can scan parts 5 and 6 before moving on to the code. * Intermediate people, who probably need to read parts 2 - 6 and understand them thoroughly before reading the code. The case studies in part 5 should be used as a guide to the patchsets. * People who have no idea what filesystems and fsck are, want to know about them, but don't have any pre-existing knowledge. > A lot of times, paraphrasing excerpts to reflect the same info in a > more compact format will help you keep audience on track (a little > longer at least). Yes, thank you for your help in spotting these kinds of problems. I've been too close to the code for years, which means I have severe myopia about things like "Am I confusing everyone?". :/ Speaking of which, am I confusing everyone? --D
