Linux-Doc Archive on
 help / color / Atom feed
From: Thorsten Leemhuis <>
To: Jonathan Corbet <>
Cc: Randy Dunlap <>,
	Greg Kroah-Hartman <>,
	Thomas Gleixner <>,,
Subject: [PATCH v4 0/3] New documentation text describing how to report issues (aka "reporting-bugs rewritten")
Date: Fri,  4 Dec 2020 07:43:47 +0100
Message-ID: <> (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:

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):

To see how the new text from v3 and v4 relates to the one from v2 or v1, compare
these files with tools like meld or kdiff3:

The patch series is against docs-next and can also be found on gitlab:
git:// reporting-bugs-v4


= Changes =

v3 -> v4
- move CC-BY-4.0 from LICENSES/preferred/ to LICENSES/dual/
- add note to CC-BY-4.0 file explaining why it's best used together with GPL
- add a note to as comment to the header of reporting-issues.rst, pointing out
only the unprocessed version of this file is available under CC-BY-4.0.

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 =

v3 submission:

v2 submission:

v1 submission:

Current version of reporting-bugs.rst

Commits to it and its predecessor:

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          | 1631 +++++++++++++++++
 Documentation/admin-guide/security-bugs.rst   |    2 +-
 .../device_drivers/ethernet/3com/vortex.rst   |    4 +-
 Documentation/process/howto.rst               |    9 +-
 LICENSES/dual/CC-BY-4.0                       |  410 +++++
 9 files changed, 2058 insertions(+), 12 deletions(-)
 create mode 100644 Documentation/admin-guide/reporting-issues.rst
 create mode 100644 LICENSES/dual/CC-BY-4.0

base-commit: ac7711427014a84ba08353df2b77f115565216d8

             reply index

Thread overview: 8+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-12-04  6:43 Thorsten Leemhuis [this message]
2020-12-04  6:43 ` [PATCH v4 1/3] LICENSES: Add the CC-BY-4.0 license Thorsten Leemhuis
2020-12-04 12:23   ` Greg Kroah-Hartman
2020-12-04 21:26     ` Jonathan Corbet
2020-12-04  6:43 ` [PATCH v4 2/3] docs: Add a new text describing how to report bugs Thorsten Leemhuis
2020-12-04  6:43 ` [PATCH v4 3/3] docs: make reporting-bugs.rst obsolete Thorsten Leemhuis
2020-12-08 17:44 ` [PATCH v4 0/3] New documentation text describing how to report issues (aka "reporting-bugs rewritten") Jonathan Corbet
2020-12-09  5:25   ` 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:

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \ \ \ \ \ \ \ \ \

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

Linux-Doc Archive on

Archives are clonable:
	git clone --mirror linux-doc/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 linux-doc linux-doc/ \
	public-inbox-index linux-doc

Example config snippet for mirrors

Newsgroup available over NNTP:

AGPL code for this site: git clone