Re: [RFC PATCH v2 06/10] MAINTAINERS: Support referencing test docs in V:

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



On 12/6/23 10:03, David Gow wrote:
On Wed, 6 Dec 2023 at 02:45, Nikolai Kondrashov
<Nikolai.Kondrashov@xxxxxxxxxx> wrote:

Support referencing test suite documentation in the V: entries of
MAINTAINERS file. Use the '*<name>' syntax (like C pointer dereference),
where '<name>' is a second-level heading in the new
Documentation/process/tests.rst file, with the suite's description.
This syntax allows distinguishing the references from test commands.
>
I like the idea here, but wonder whether it makes sense to put all of
these tests into a single 'tests.rst' file. There's already lots of
existing documentation scattered around the tree, and while keeping
all of the testing information in one place does have advantages, I
think there's a lot to be said for keeping subsystem-specific test
docs alongside the rest of the documentation for the subsystem itself.
And it'd be less work, as the docs are already there.

So, could we just make this a path under Documentation/ (possibly with
an #anchor if we need to reference just one part of a file)?

e.g., something like these, all of which are existing docs:
V: *Documentation/dev-tools/kasan.rst#Tests
or
V: *Dcoumentation/RCU/torture.rst
or
V: *Documentation/gpu/automated_testing.rst
or
V: *Documentation/process/maintainer-kvm-x86.rst#Testing

(We could even get rid of the '*' and just use 'Documentation/' as a
prefix, or the executable bit on the file, or similar to distinguish
these from scripts.)

If we wanted to be very brave, we could extend this further to
arbitrary webpages, like:
V: https://git.kernel.org/pub/scm/fs/xfs/xfstests-dev.git/tree/README

Sure, having a filename (in a specific directory) or a just piece of path in the source (sub)tree would work too. The idea of single file was mostly to make it easier to access a *catalog* of all tests in a single file with small bits of introductory documentation, pointing to the more detailed documentation (wherever you prefer it to be) from there.

URLs would work as well for pointing to the docs, but they become somewhat more cumbersome and error-prone for use in Tested-with: tags (if we would like them), just because of their length and complexity. If we won't care for that, it's not a problem.

However, overall, I would be cautious multiplying the ways tests can be specified in V: entries (and Tested-with: tags), as that could quickly become unwieldy and confusing for humans, who are expected to be interpreting and writing them. Especially if the syntax could potentially be ambiguous.

Nick





[Index of Archives]     [Linux Wireless]     [Linux Kernel]     [ATH6KL]     [Linux Bluetooth]     [Linux Netdev]     [Kernel Newbies]     [Share Photos]     [IDE]     [Security]     [Git]     [Netfilter]     [Bugtraq]     [Yosemite News]     [MIPS Linux]     [ARM Linux]     [Linux Security]     [Linux RAID]     [Linux ATA RAID]     [Samba]     [Device Mapper]

  Powered by Linux