[PATCH v3 15/18] Documentation: kunit: add documentation for KUnit

[Brendan Higgins]

Sorry, to email so many people, but there are a lot of maintainers in
this directory.

On Wed, May 15, 2019 at 6:45 AM Jonathan Corbet <corbet at lwn.net> wrote:
>
> On Tue, 14 May 2019 16:19:02 -0700
> Brendan Higgins <brendanhiggins at google.com> wrote:
>
> > Hmmm...probably premature to bring this up, but Documentation/dev-tools/
> > is kind of thrown together.
>
> Wait a minute, man... *I* created that directory, are you impugning my
> work? :)

What?! I would never! ;-)

Context for the people I just added: I proposed documentation for a
new development tool. Jon very reasonably suggested it should go in
Documentation/dev-tools/, which is not very well organized. This in
turn prompted a discussion about cleaning it up.

> But yes, "kind of thrown together" is a good description of much of
> Documentation/.  A number of people have been working for years to make
> that better, with some success, but there is a long way to go yet.  The
> dev-tools directory is an improvement over having that stuff scattered all
> over the place — at least it's actually thrown together — but it's not the
> end point.
>
> > It would be nice to provide a coherent overview, maybe provide some
> > basic grouping as well.
> >
> > It would be nice if there was kind of a gentle introduction to the
> > tools, which ones you should be looking at, when, why, etc.
>
> Total agreement.  All we need is somebody to write it!  :)

I wouldn't mind taking a stab at it in a later patchset.

My initial idea: there is a bunch more stuff that needs to be added
here, so probably don't want to do it all at once.

I am thinking the first step is just to categorize things in a
sensible manner so somebody doesn't look at the index and see *all the
tools* immediately causing their eyes to glaze over. From first
glances it looks like the users of these tools is going to be somewhat
disjoint.

Maybe break things apart by who and how someone would use the tool. For example,

It looks like Coccinelle is going to be used primarily by people doing
code janitor work and large scale changes.

Sparse seems like a presubmit tool.

gdb and kdb are likely used by everyone for debugging.

kselftest (and, if I get my way, KUnit) are used primarily people
contributing new features (this is one I have more of a vested
interest in, so I will leave it at that, but the point is: I think
they would go together).

Most of the remaining tools (except gcov) look like the kind of long
running tests that you point at a stable tree and let it sit and catch
bugs. Super useful, but I don't think your average kernel dev is going
to be trying to set it up or run it. Please correct me if I am wrong.

So that leaves gcov. I think it is awesome, but I am not sure how to
categorize it. Definitely want some advice here.

Once everything is appropriately categorized by shape, in (a)
subsequent patchset(s) we can tie each one in with a guide, not just
on how to use the tool, but how the workflow looks for someone who
uses that tool. For example, we might want to a guide on how to do
large scale changes in the Linux kernel and have that tie in with
Coccinelle. For kselftest and KUnit, we might want to provide a guide
on how to test Linux kernel code, which would cover when and how to
use each.

Anyway, just a vague sketch. Looking forward to hear what everyone thinks!