• Thorsten Leemhuis's avatar
    docs: Add a new text describing how to report bugs · 3e544d72
    Thorsten Leemhuis authored
    Add a mostly finished document describing how to report issues with the
    Linux kernel to its developers. It is designed to be a lot more straight
    forward and easier to follow than the current text about this
    (Documentation/admin-guide/reporting-bugs.rst); at the same time the new
    text should be more helpful for people unfamiliar with the topic, as it
    provides a lot more details, too.
    
    The main work on the text is done, but some polishing is still needed.
    The text also needs to be reviewed by more people and a few issues still
    might need some discussion. To make these tasks easier, it was decided
    ([1]) to add this document to the kernel sources in parallel to the
    existing text; the latter will be removed once this text is considered
    good enough(tm).
    
    This document is quite long and provides a lot of details, but was
    carefully crafted to make sure it's can also serve people that are in a
    hurry. That's mainly achieved by having a TDLR and a step-by-step guide,
    which should be good enough for quite a lot of people. Everybody that
    wants or need more explanations can find them in a reference section,
    which describes all the needed steps in detail.
    
    Thanks to this structure the text can work for kernel developers that
    just need to look something up, experienced FLOSS contributors that are
    unfamiliar with the kernel's bug reporting workflow, and users reporting
    something upstream for the first time. The text is thus a bit like the
    kernel itself, which works well for embedded machines, a typical desktop
    PC, cloud servers, and HPC.
    
    The document was written in the hope it will improve the quality of the
    bug reports, especially those that come from people unfamiliar with how
    Linux kernel development works. Sadly quite a few reports from this
    group are currently of poor quality and/or get submitted to the wrong
    place. Part of the problem is the old reporting-bugs document, as it
    makes its essence hard to grasp; it's and also inaccurate and slightly
    outdated in a few spots. Due to this quite a few valid reports are
    ignored in the end, which is annoying for those that compiled them and
    bad for the kernel's quality.
    
    The document near the top points out that it's still unfinished, but
    nevertheless ready for consumption. Those few areas in the text that
    might need some further discussion contain a note pointing this out.
    Besides lack of review from core developers there is only one major
    issue left: the section 'Decode failure message' is known to be
    outdated: it's waiting for someone familiar with the topic to write
    something up or give at least provide some hints and pointers what to
    write there.
    
    The new document is dual-licensed under GPL-2.0+ or CC-BY-4.0. The
    latter is way more liberal and makes it attractive to use this text as a
    base when writing about this topic on websites or in books. This
    hopefully increases the chances that such texts are accurate and stick
    to official way of doing things.
    
    [1] https://lkml.kernel.org/r/20201118172958.5b014a44@lwn.netSigned-off-by: default avatarThorsten Leemhuis <linux@leemhuis.info>
    CC: Thomas Gleixner <tglx@linutronix.de>
    CC: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
    CC: Christoph Hellwig <hch@lst.de>
    Link: https://lore.kernel.org/r/e2db808f954744b79f10937a923d9c99bdca1fca.1607063223.git.linux@leemhuis.infoSigned-off-by: default avatarJonathan Corbet <corbet@lwn.net>
    3e544d72
index.rst 2.26 KB