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

[Thorsten Leemhuis]

On 19.02.24 23:07, Jonathan Corbet wrote:
> Thorsten Leemhuis <linux@xxxxxxxxxxxxx> 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.

No problem, I didn't expect this to be something that would be merged
quickly.

>  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 see you point and partly agree. But at the same time I partly disagree
as well: the gist of the old document is not that different from what
segment 3 of the TLDR in the new document outlines.

The main problem I thus see is that readers will likely be scared by the
wall of text and thus will look for some shorter guide. We could avoid
that by basically replacing the content of
Documentation/admin-guide/bug-bisect.rst with something that is round
about a copy of segment 3 of the TLDR with a short new and better intro
on top of it (e.g. something along the lines of "This assumes that you
(a) already set up everything up to compile your own Linux kernel from
sources found in a local Git clone (b) checked if the regression was
already solved in mainline (c) prepared, validated, and packed to the
side a .config file with a kernel version known to be working. If any of
this is not the case, you likely are better of following the
Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst instead.")

>  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.

As you can see from above I partly agree with that. But the old guide
(or what I suggested doing above!) OTOH is so terse that it's not that
different from what the man-page of 'git bisect' already outlines --
except that it's a kernel specific example. Makes me wonder if that's
really worth it, but I guess it is.

> I'll repeat a question I've asked before: should we create a separate
> "tutorials" book for this kind of material?

To be honest I'm not sure if I can help here, as I'm not totally sure
that I got your intend / long-term goal.

>  I honestly think that the
> readers for this kind of documentation will be a different crowd,

"Different" from what? I mean, my new guide is added to the "user's and
administrator's guide" book and from what I see we live in times where
many users and admins might never have compiled a kernel, but still
occasionally encounter a situation where they want to report a bug
upstream. That guide allows them to do this. And even if they have
occasionally complied a kernel in the past the guide works well for
them, as the TLDR is easy to follow for such readers.

> and
> everybody might be better off if we put the tutorial material in one
> place where they can find it easily.

But do you expect more documents like that? FWIW, I for one don't plan
to write anything more like this (revising the "reporting issues"
document is next on my list). Unless more is forthcoming I guess a new
book is not worth it.

> Regardless, thanks for doing this,

Thx for saying that!

Ciao, Thorsten