Make Documentation/admin-guide/reporting-issues.rst point to the newly
created document about regressions
(Documentation/admin-guide/regressions-regressions.rst). This allows to
shorten a few explanations the new document describes better and in more
detail.
While at it move the copyright hint to the end of the file and remove
quotes around links to other places in the documentation. Both issues
came up during the review of the new documents about regressions.
Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
Link: https://lore.kernel.org/r/f20114eaddc356a8c79dd62812a6c7f4ca5d87b9.1644994117.git.linux@leemhuis.info
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The conversion tools used during DocBook/LaTeX/html/Markdown->ReST
conversion and some cut-and-pasted text contain some characters that
aren't easily reachable on standard keyboards and/or could cause
troubles when parsed by the documentation build system.
Replace the occurences of the following characters:
- U+00a0 (' '): NO-BREAK SPACE
as it can cause lines being truncated on PDF output
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/551a2af0e654226067e5c376d3e2d959cc738f39.1623826294.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Make people CC the recently created mailing list dedicated to Linux
kernel regressions when reporting one. Some paragraphs had to be
reshuffled and slightly rewritten during the process, as the text
otherwise would have gotten unnecessarily hard to follow.
Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Link: https://lore.kernel.org/r/ac28089d710d5d41f295221bc726555ba32f4984.1617967127.git.linux@leemhuis.info
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Replace it with olddefconfig. oldnoconfig didn't do what the document
suggests (it aliased to olddefconfig), and isn't available since 4.19.
Ref: 04c459d204 ("kconfig: remove oldnoconfig target")
Ref: 312ee68752 ("kconfig: announce removal of oldnoconfig if used")
Signed-off-by: Ismael Luceno <ismael@iodev.co.uk>
Link: https://lore.kernel.org/r/20210331163541.28356-1-ismael@iodev.co.uk
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
A pile of small fixes:
- don't quote terms like vanilla, mainline, and stable, unless in they
occur in places where readers new to the kernel might see them for the
first time
- make people rule out that vendor patches are interfering if they face
a regression in a stable or longterm kernel they saw in a vendor
kernel for the first time
- s/bugs/issues/ in a selected spots
- exchange two headlines that got mixed up somehow
- add a few links to some of the steps in the guide
- Greg mentioned sending reports to the stable mailing list is
sufficient, so remove the "CC stable maintainers" bits
- fix a few typos and mistakes in the text, with a few very small
improvements along the way
Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
Link: https://lore.kernel.org/r/07bca15d8465b8e234537feb8841dd2ff20243bc.1617113469.git.linux@leemhuis.info
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Make the TLDR a bit shorter while improving it at the same time by going
straight to the aspects readers are more interested it. The change makes
the process especially more straight-forward for people that hit a
regression in a stable or longterm kernel. Due to the changes the TLDR
now also matches the step by step guide better.
Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
Link: https://lore.kernel.org/r/762ccd7735315d2fdaa79612fccc1f474881118b.1617113469.git.linux@leemhuis.info
[ jc: fixed transposed _` as noted by Thorsten ]
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Remove the WIP and two FIXME notes in the text to make it official, as
it's now considered fully ready for consumption. To make sure this
step is okay for people the intent of this change and the latest version
of the text were posted to ksummit-discuss; nobody complained, thus
lets move ahead.
Add a footer to point out people can contact Thorsten directly in case
they find something to improve in the text.
Dear reporting-bugs.rst, I'm sorry to tell you, but that makes you fully
obsolete and we thus have to let you go now. Thank you very much for
your service, you in one form or another have been around for a long
time. I'm sure over the years you got read a lot and helped quite a few
people. But it's time to retire now. Rest in peace.
Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
CC: Harry Wei <harryxiyou@gmail.com>
CC: Alex Shi <alex.shi@linux.alibaba.com>
CC: Federico Vaga <federico.vaga@vaga.pv.it>
CC: Greg KH <gregkh@linuxfoundation.org>
Link: https://lore.kernel.org/r/49c674c2d304d87e6259063580fda05267e8c348.1617113469.git.linux@leemhuis.info
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Provide a shorter and easier process for users that deal with
regressions in stable and longterm kernels, as those should be reported
quickly.
To realize this in the least-confusing way and without having steps
multiple times in different places, split the 'search for existing
reports' into two. That has the additinal benefit that users will search
for them quickly when going through the step by step guide and thus will
save them trouble if the find reports.
Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
CC: Randy Dunlap <rdunlap@infradead.org>
Link: https://lore.kernel.org/r/d934c15e536bceeff5c40a126930ddf803548e08.1616181657.git.linux@leemhuis.info
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Reorder some steps where the order in which the readers perform them is
not crucial. This is a preparation for a later change that would make
the text much more complex otherwise.
Content just moved, not changed at all in the process.
Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
Link: https://lore.kernel.org/r/8dfc58efde25a05ccf9bf85929826c4b1b9e09c5.1616181657.git.linux@leemhuis.info
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Tell users that reporting bugs with vendor kernels which are only
slightly patched can be okay in some situations, but point out there's a
risk in doing so.
Adjust some related sections to make them compatible and a bit clearer.
At the same time make them less daunting: we want users to report bugs,
even if they can't test vanilla mainline kernel.
Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
CC: Randy Dunlap <rdunlap@infradead.org>
Link: https://lore.kernel.org/r/652ee20eb36228f5d7ca842299faa4cb472feedb.1616181657.git.linux@leemhuis.info
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Replace placeholder text about decoding stack traces with a section that
properly describes what a typical user should do these days. To make
it works for them, add a paragraph in an earlier section to ensure
people build their kernels with everything that's needed to decode stack
traces later.
Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
Reviewed-by: Qais Yousef <qais.yousef@arm.com>
Acked-by: Vlastimil Babka <vbabka@suse.cz>
Link: https://lore.kernel.org/r/20210215172857.382285-1-linux@leemhuis.info
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
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.net
Signed-off-by: Thorsten 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.info
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Thorsten Leemhuis
Mauro Carvalho Chehab
Ismael Luceno