Re: [PATCH 01/14] xfs: document the motivation for online fsck design

["Darrick J. Wong" <djwong@kernel.org>]

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