Documentation/security-bugs: move from admin-guide/ to process/

Jiri Kosina, Jonathan Corbet, and Willy Tarreau all expressed a desire
to move this document under process/.

Create a new section for

Documentation/security-bugs: move from admin-guide/ to process/

Jiri Kosina, Jonathan Corbet, and Willy Tarreau all expressed a desire
to move this document under process/.

Create a new section for security issues in the index and group it with
embargoed-hardware-issues.

I'm doing this at the start of the series to make all the subsequent
changes show up in 'git blame'.

Existing references were updated using:

git grep -l security-bugs ':!Documentation/translations/' | xargs sed -i 's|admin-guide/security-bugs|process/security-bugs|g'
git grep -l security-bugs Documentation/translations/ | xargs sed -i 's|Documentation/admin-guide/security-bugs|Documentation/process/security-bugs|g'
git grep -l security-bugs Documentation/translations/ | xargs sed -i '/Original:/s|\.\./admin-guide/security-bugs|\.\./process/security-bugs|g'

Notably, the page is not moved in the translations (due to my lack of
knowledge of these languages), but the translations have been updated
to point to the new location of the original document where these
references exist.

Link: https://lore.kernel.org/all/[email protected]/
Suggested-by: Jiri Kosina <[email protected]>
Cc: Alex Shi <[email protected]>
Cc: Yanteng Si <[email protected]>
Cc: Hu Haowen <[email protected]>
Cc: Federico Vaga <[email protected]>
Cc: Tsugikazu Shibata <[email protected]>
Cc: Minchan Kim <[email protected]>
Cc: Jeimi Lee <[email protected]>
Cc: Carlos Bilbao <[email protected]>
Cc: Akira Yokosawa <[email protected]>
Signed-off-by: Vegard Nossum <[email protected]>
Acked-by: Carlos Bilbao <[email protected]>
Reviewed-by: Yanteng Si <[email protected]>
Reviewed-by: Akira Yokosawa <[email protected]>
Acked-by: Federico Vaga <[email protected]>
Reviewed-by: Bagas Sanjaya <[email protected]>
Link: https://lore.kernel.org/r/[email protected]
Signed-off-by: Greg Kroah-Hartman <[email protected]>

show more ...

docs: reporting-issues.rst: link new document about regressions

Make Documentation/admin-guide/reporting-issues.rst point to the newly
created document about regressions
(Documentation/admin-guide/r

docs: reporting-issues.rst: link new document about regressions

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 <[email protected]>
Link: https://lore.kernel.org/r/f20114eaddc356a8c79dd62812a6c7f4ca5d87b9.1644994117.git.linux@leemhuis.info
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

docs: admin-guide: reporting-issues.rst: replace some characters

The conversion tools used during DocBook/LaTeX/html/Markdown->ReST
conversion and some cut-and-pasted text contain some characters th

docs: admin-guide: reporting-issues.rst: replace some characters

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 <[email protected]>
Link: https://lore.kernel.org/r/551a2af0e654226067e5c376d3e2d959cc738f39.1623826294.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

docs: reporting-issues.rst: CC subsystem and maintainers on regressions

When reporting a regression, users ideally should CC the subsystem and
its maintainers, as that will ensure they get aware of

docs: reporting-issues.rst: CC subsystem and maintainers on regressions

When reporting a regression, users ideally should CC the subsystem and
its maintainers, as that will ensure they get aware of the regression
quickly. And if the culprit is known, they should also CC everyone who
signed if off; the text mentioned the latter in once place already, but
forgot to do so in two other areas where it's relevant.

While fixing this also remind readers to check the mailing list archives
for issues that need to be reported to a bug tracker, as someone might
have reported it by mail only.

All of this got triggered by a recent report where these changes would
have made a difference.

Signed-off-by: Thorsten Leemhuis <[email protected]>
Link: https://lore.kernel.org/lkml/[email protected]/
Link: https://lore.kernel.org/lkml/CAJZ5v0hX2StQVttAciHYH-urUH+Hi92z9z2ZbcNgQPt0E2Jpwg@mail.gmail.com/
Link: https://lore.kernel.org/r/dd13f10c30e79e550215e53a8103406daec4e593.1618482489.git.linux@leemhuis.info
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

docs: reporting-issues: make people CC the regressions list

Make people CC the recently created mailing list dedicated to Linux
kernel regressions when reporting one. Some paragraphs had to be
reshu

docs: reporting-issues: make people CC the regressions list

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 <[email protected]>
Reviewed-by: Greg Kroah-Hartman <[email protected]>
Link: https://lore.kernel.org/r/ac28089d710d5d41f295221bc726555ba32f4984.1617967127.git.linux@leemhuis.info
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

docs: reporting-issues: Remove reference to oldnoconfig

Replace it with olddefconfig. oldnoconfig didn't do what the document
suggests (it aliased to olddefconfig), and isn't available since 4.19.

docs: reporting-issues: Remove reference to oldnoconfig

Replace it with olddefconfig. oldnoconfig didn't do what the document
suggests (it aliased to olddefconfig), and isn't available since 4.19.

Ref: 04c459d20448 ("kconfig: remove oldnoconfig target")
Ref: 312ee68752fa ("kconfig: announce removal of oldnoconfig if used")
Signed-off-by: Ismael Luceno <[email protected]>
Link: https://lore.kernel.org/r/[email protected]
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

docs: reporting-issues: reduce quoting and assorted fixes

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 ke

docs: reporting-issues: reduce quoting and assorted fixes

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 <[email protected]>
Link: https://lore.kernel.org/r/07bca15d8465b8e234537feb8841dd2ff20243bc.1617113469.git.linux@leemhuis.info
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

docs: reporting-issues.rst: reshuffle and improve TLDR

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 mak

docs: reporting-issues.rst: reshuffle and improve TLDR

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 <[email protected]>
Link: https://lore.kernel.org/r/762ccd7735315d2fdaa79612fccc1f474881118b.1617113469.git.linux@leemhuis.info
[ jc: fixed transposed _` as noted by Thorsten ]
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

docs: make reporting-issues.rst official and delete reporting-bugs.rst

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

docs: make reporting-issues.rst official and delete reporting-bugs.rst

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 <[email protected]>
Reviewed-by: Greg Kroah-Hartman <[email protected]>
CC: Harry Wei <[email protected]>
CC: Alex Shi <[email protected]>
CC: Federico Vaga <[email protected]>
CC: Greg KH <[email protected]>
Link: https://lore.kernel.org/r/49c674c2d304d87e6259063580fda05267e8c348.1617113469.git.linux@leemhuis.info
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

docs: reporting-issues.rst: improved process esp. for stable regressions

Provide a shorter and easier process for users that deal with
regressions in stable and longterm kernels, as those should be

docs: reporting-issues.rst: improved process esp. for stable regressions

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 <[email protected]>
CC: Randy Dunlap <[email protected]>
Link: https://lore.kernel.org/r/d934c15e536bceeff5c40a126930ddf803548e08.1616181657.git.linux@leemhuis.info
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

docs: reporting-issues.rst: duplicate sections for reviewing purposes

This duplicates two section to make the diff in the next patch a bit
easier to gasp for humans.

Straight copy, no content chang

docs: reporting-issues.rst: duplicate sections for reviewing purposes

This duplicates two section to make the diff in the next patch a bit
easier to gasp for humans.

Straight copy, no content changes.

Signed-off-by: Thorsten Leemhuis <[email protected]>
Link: https://lore.kernel.org/r/ef85edc8466f035eb243dd6629429ad4fd0565d8.1616181657.git.linux@leemhuis.info
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

docs: reporting-issues.rst: reorder some steps

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

docs: reporting-issues.rst: reorder some steps

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 <[email protected]>
Link: https://lore.kernel.org/r/8dfc58efde25a05ccf9bf85929826c4b1b9e09c5.1616181657.git.linux@leemhuis.info
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

docs: reporting-issues.rst: tone down 'test vanilla mainline' a little

Tell users that reporting bugs with vendor kernels which are only
slightly patched can be okay in some situations, but point ou

docs: reporting-issues.rst: tone down 'test vanilla mainline' a little

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 <[email protected]>
CC: Randy Dunlap <[email protected]>
Link: https://lore.kernel.org/r/652ee20eb36228f5d7ca842299faa4cb472feedb.1616181657.git.linux@leemhuis.info
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

docs: reporting-issues.rst: fix small typos and style issues

Fix a typo and change "head over" to "scroll down", as suggested by Jon
when reviewing another patch that used the phrase the same way.

docs: reporting-issues.rst: fix small typos and style issues

Fix a typo and change "head over" to "scroll down", as suggested by Jon
when reviewing another patch that used the phrase the same way.

Signed-off-by: Thorsten Leemhuis <[email protected]>
Link: https://lore.kernel.org/r/fb845d2f1db6138337203bbfac419c04b5f28053.1616181657.git.linux@leemhuis.info
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

docs: reporting-issues.rst: explain how to decode stack traces

Replace placeholder text about decoding stack traces with a section that
properly describes what a typical user should do these days. T

docs: reporting-issues.rst: explain how to decode stack traces

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 <[email protected]>
Reviewed-by: Qais Yousef <[email protected]>
Acked-by: Vlastimil Babka <[email protected]>
Link: https://lore.kernel.org/r/[email protected]
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

docs: reporting-issues: move 'outdated, need help' note to proper place

Move the 'this section is a placeholder for now and needs help by
someone with domain knowledge' note one section upwards to t

docs: reporting-issues: move 'outdated, need help' note to proper place

Move the 'this section is a placeholder for now and needs help by
someone with domain knowledge' note one section upwards to the place
where it belongs: the 'Decode failure messages' section.

Signed-off-by: Thorsten Leemhuis <[email protected]>
Link: https://lore.kernel.org/r/d3894ba4a302beed661304cbcdc062c6dcfe3e58.1607489877.git.linux@leemhuis.info
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

docs: Add a new text describing how to report bugs

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
fo

docs: Add a new text describing how to report bugs

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/[email protected]

Signed-off-by: Thorsten Leemhuis <[email protected]>
CC: Thomas Gleixner <[email protected]>
CC: Greg Kroah-Hartman <[email protected]>
CC: Christoph Hellwig <[email protected]>
Link: https://lore.kernel.org/r/e2db808f954744b79f10937a923d9c99bdca1fca.1607063223.git.linux@leemhuis.info
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...