Re: [PATCH v1] docs: new text on bisecting which also covers bug validation

[Vegard Nossum <vegard.nossum@oracle.com>]

On 19/02/2024 23:07, Jonathan Corbet wrote:
> Thorsten Leemhuis <linux@leemhuis.info> writes:
> 
>> Replace the existing brief explanation on bisecting regressions with a
>> text describing the whole process from beginning to end -- while also
>> describing how to validate if a problem is still present in mainline.
>> This "two in one" approach is possible, as checking whenever a bug is in
>> mainline is one of the first steps before performing a bisection anyway
>> and thus described. Due to this approach the text also works quite
>> nicely in conjunction with
>> Documentation/admin-guide/reporting-issues.rst, as it covers all typical
>> cases where users will need to build a kernel in exactly the same order.
> 
> I have scanned over this; don't really have a time to do a detailed
> reading at this point.  My overall impression is: it's useful
> information, but I think we're going to overwhelm people.  I worry that
> we're replacing a one-page file on how to do a bisect with a 1,900-line
> beast.  I suspect there are whole classes of readers who want the new
> stuff, but there are others who would be better served by something much
> more terse.

My vote would be to include the new document "soon" (perhaps after
Petr's extensive comments have been addressed), but keep the existing,
short document around as well.

Yes, the new doc is long and perhaps overwhelming for some, but nobody
is forced to use it and its existence in the kernel documentation does
not in any way detract from the documentation as a whole.

I also think the best feedback is going to come from users attempting
to use these steps for their real regressions. Once merged, we
(Thorsten or anybody) can attempt to incorporate that feedback in
increments.

Perfect is the enemy of good, etc.

> I'll repeat a question I've asked before: should we create a separate
> "tutorials" book for this kind of material?  I honestly think that the
> readers for this kind of documentation will be a different crowd, and
> everybody might be better off if we put the tutorial material in one
> place where they can find it easily.

Something I really like about the current set of books is that they are,
at least in theory, roughly divided by their target audience
(user/admin, userspace dev, kernel dev). I'd worry that "tutorials"
as a top-level book would unintentionally end up as a very mixed bag of
documents that don't have a clearly defined target audience.

So FWIW I don't think "tutorials" should be a new top-level book. Maybe
it could be its own section under admin-guide, but in that case we
should have a clear idea of what other documents we intend to move there
as well.

Also, I'm not sure if this bisection document is really even a tutorial;
I feel like tutorials aim to teach, while this document seems more like
a guide/howto or run-book. Maybe this is splitting hairs, though :-)


Vegard