Re: [PATCH v2 0/2] Revamp admin-guide/tainted-kernels.rst to make it more comprehensible

[Jonathan Corbet]

On Tue,  8 Jan 2019 20:40:05 +0100
Thorsten Leemhuis <linux@xxxxxxxxxxxxx> wrote:

> Hi! This is the second version of my patch to make
> admin-guide/tainted-kernels.rst more comprehensible. It got triggered while
> working on an update for reporting-bugs.rst, as improving the documentation
> around reporting bugs and regressions was one of the main things that a lot of
> people wanted to see while regression tracking was discussed in the kernel and
> maintainer summit 2017 in Prague.
> 
> This is the second version of the patch, which became a patch set, as it now
> contains a script Randy (thx) provided during the discussion of the first
> version. 
> 
> Please review and consider applying.

OK, so we're so close...  I think the patches are good; they are a welcome
improvement to the documentation and the script looks great.  Thanks for
doing this!  Patches applied.

Now for the "I love your patch, something to improve part" :)

 - Patch 1 didn't apply to docs-next; probably you got caught by the
   fast-forward to 5.0-rc1.  I've applied it to 4.20 then merged to
   resolve the conflict in tools/Makefile.

 - I was tempted to ask you to redo the changelogs, but ended up just
   tweaking them myself.  Changelogs should focus on what the patch does
   and why; they aren't usually the place for the history of how the patch
   came to exist in its current form.  I'll append what actually got
   committed.  (Filling to 72 columns or so is also a nice touch for
   changelogs).

Thanks for doing this work - looking forward to more.

jon

The reworked changelogs are:

    tools: add a kernel-chktaint to tools/debugging
    
    Add a script to the tools/ directory that shows if or why the running
    kernel was tainted. The script was mostly written by Randy Dunlap; I
    enhanced the script a bit.  There does not appear to be a good home for
    this script. so create tools/debugging for tools of this nature.
    
    Signed-off-by: Randy Dunlap <rdunlap@xxxxxxxxxxxxx>
    Signed-off-by: Thorsten Leemhuis <linux@xxxxxxxxxxxxx>
    [ jc: rewrote changelog ]
    Signed-off-by: Jonathan Corbet <corbet@xxxxxxx>

-----

    docs: Revamp tainted-kernels.rst to make it more comprehensible
    
    Add a section about decoding /proc/sys/kernel/tainted, create a more
    understandable intro and a hopefully explain better the tainted flags in
    bugs, oops or panics messages. Only thing missing then is a table that
    quickly describes the various bits and taint flags before going into more
    detail, so add that as well.
    
    That table is partly based on a section from Documentation/sysctl/kernel.txt
,
    but a bit more compact. To avoid confusion I added the shortened version to
    kernel.txt; the same table is used in three different places now:
    ./tools/debugging/kernel-chktaint,
    Documentation/admin-guide/tainted-kernels.rst and
    Documentation/sysctl/kernel.txt
    
    During review of v1 (see above) a number of existing issues with the text
    were raised, like outdated usages as well as incomplete or missing
    descriptions.  Address most of those as well.
    
    Signed-off-by: Thorsten Leemhuis <linux@xxxxxxxxxxxxx>
    [jc: tightened up changelog]
    Signed-off-by: Jonathan Corbet <corbet@xxxxxxx>


-- 
Jonathan Corbet / LWN.net / corbet@xxxxxxx