From: Thorsten Leemhuis <linux@leemhuis.info>
To: Jonathan Corbet <corbet@lwn.net>
Cc: Randy Dunlap <rdunlap@infradead.org>,
Greg Kroah-Hartman <gregkh@linuxfoundation.org>,
linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org
Subject: [PATCH v3 0/3] New documentation text describing how to report issues (aka "reporting-bugs rewritten")
Date: Tue, 24 Nov 2020 09:00:00 +0100 [thread overview]
Message-ID: <cover.1606137108.git.linux@leemhuis.info> (raw)
This series adds a new and 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 yet more detailed than the current text about this
(Documentation/admin-guide/reporting-bugs.rst). The new text still needs to be
reviewed by more people and a few open issues will need discussion. To make
these tasks easier, it was decided to add this document to the kernel sources in
parallel to the existing text for now:
https://lkml.kernel.org/r/20201118172958.5b014a44@lwn.net
The first patch in the series adds the CC-BY-4.0 license to the
LICENSES/preferred/ directory, as the main author wants to make it easy for
others to use the new text as a base when writing about this topic in books or
on websites. He for now went with for dual-licensing the text under GPL-2.0+ and
CC-BY-4.0. We shouldn't lose much when people use the more liberal of the two,
but gain one thing: it increases chances that texts about this topic are based
on this one, which should make them more accurate and to our liking.
The last patch in the series adds a note to
Documentation/admin-guide/reporting-bugs.rst, declaring it obsolete and telling
readers to head over to the new text, as discussed after the v2 submission.
To see how the new text relates to the current reporting-bugs.rst document, see
v2 of this patchset, which gradually replaced the old text with the new (which
hasn't changed much since then):
https://lore.kernel.org/lkml/cover.1605203187.git.linux@leemhuis.info/
To see how the new text from v3 relates to the one from v2 or v1, compare these
files with tools like meld or kdiff3:
https://gitlab.com/knurd42/linux/-/raw/reporting-bugs/Documentation/admin-guide/reporting-bugs-v3-wrapped.rst
https://gitlab.com/knurd42/linux/-/raw/reporting-bugs/Documentation/admin-guide/reporting-bugs-v2-wrapped.rst
https://gitlab.com/knurd42/linux/-/raw/reporting-bugs/Documentation/admin-guide/reporting-bugs-v1-wrapped.rst
The patch series is against docs-next and can also be found on gitlab:
git://git@gitlab.com:knurd42/linux.git reporting-bugs-v3
[1] https://lkml.kernel.org/r/20201118172958.5b014a44@lwn.net
= Changes =
v2 -> v3
- drop the RFC tag
- add CC-BY-4.0 to LICENSES/preferred/
- instead of adding the new text in small parts while gradually replacing the
old text simply dump the whole new text in a new file in one go
- add a note at the top pointing out the text is not completely finished yet,
but ready for consumption
- add a few notes to the text pointing to issues that need discussion or work;
this until now was done in the patch
- let the automarkup extension handle links to Documentation/whatever instead of
using an explicit :ref:
- leave scripts/ver_linux untouched
- a handful of small improvements and fixes in the main text
- add a patch that makes reporting-bugs.rst obsolete
v1 -> v2
- all over: a whole lot of spelling fixes and small improvements. Many thx to
suggestions from Randy Dunlap (many thx!).
- use "ref:" to reference MAINTAINERs file
- the licensing advice is now a rst comment near the top
- reshuffle and rewrite some parts to make them more straight forward:
- The short guide (aka TL;DR)" (patch 2)
- Locate kernel area that causes the issue (patch 9)
- Install a fresh kernel for testing (patch 15)
= Links =
v2 submission:
https://lore.kernel.org/lkml/cover.1605203187.git.linux@leemhuis.info/
v1 submission:
https://lore.kernel.org/lkml/cover.1601541165.git.linux@leemhuis.info/
Current version of reporting-bugs.rst
https://www.kernel.org/doc/html/latest/admin-guide/reporting-bugs.html
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/Documentation/admin-guide/reporting-bugs.rst
Commits to it and its predecessor:
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/log/Documentation/admin-guide/reporting-bugs.rst
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/log/REPORTING-BUGS
Thorsten Leemhuis (3):
LICENSES: Add the CC-BY-4.0 license
docs: Add a new text describing how to report bugs
docs: make reporting-bugs.rst obsolete
Documentation/admin-guide/README.rst | 4 +-
Documentation/admin-guide/bug-bisect.rst | 2 +-
Documentation/admin-guide/index.rst | 3 +-
Documentation/admin-guide/reporting-bugs.rst | 5 +
.../admin-guide/reporting-issues.rst | 1626 +++++++++++++++++
Documentation/admin-guide/security-bugs.rst | 2 +-
.../device_drivers/ethernet/3com/vortex.rst | 4 +-
Documentation/process/howto.rst | 9 +-
LICENSES/preferred/CC-BY-4.0 | 405 ++++
9 files changed, 2048 insertions(+), 12 deletions(-)
create mode 100644 Documentation/admin-guide/reporting-issues.rst
create mode 100644 LICENSES/preferred/CC-BY-4.0
base-commit: ac7711427014a84ba08353df2b77f115565216d8
--
2.28.0
next reply other threads:[~2020-11-24 8:00 UTC|newest]
Thread overview: 14+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-11-24 8:00 Thorsten Leemhuis [this message]
2020-11-24 8:00 ` [PATCH v3 1/3] LICENSES: Add the CC-BY-4.0 license Thorsten Leemhuis
2020-11-24 9:18 ` Christoph Hellwig
2020-11-24 9:31 ` Thorsten Leemhuis
2020-11-24 9:36 ` Christoph Hellwig
2020-11-24 10:07 ` Thorsten Leemhuis
2020-11-24 12:11 ` Matthew Wilcox
2020-11-24 13:06 ` Thorsten Leemhuis
2020-11-30 14:51 ` Jonathan Corbet
2020-12-01 14:43 ` Christoph Hellwig
2020-12-01 20:45 ` Thorsten Leemhuis
2020-11-26 10:11 ` Thorsten Leemhuis
2020-11-24 8:00 ` [PATCH v3 2/3] docs: Add a new text describing how to report bugs Thorsten Leemhuis
2020-11-24 8:00 ` [PATCH v3 3/3] docs: make reporting-bugs.rst obsolete Thorsten Leemhuis
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=cover.1606137108.git.linux@leemhuis.info \
--to=linux@leemhuis.info \
--cc=corbet@lwn.net \
--cc=gregkh@linuxfoundation.org \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=rdunlap@infradead.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).