The use of automated tools to find bugs in random locations of the kernel
induces a raise of security reports even if most of them should just be
reported as regular bugs. This patch is an attempt at drawing a line
between what qualifies as a security bug and what does not, hoping to
improve the situation and ease decision on the reporter's side.
It defers the enumeration to a new file, threat-model.rst, that tries
to enumerate various classes of issues that are and are not security
bugs. This should permit to more easily update this file for various
subsystem-specific rules without having to revisit the security bug
reporting guide.
Cc: Greg KH <gregkh@linuxfoundation.org>
Cc: Leon Romanovsky <leon@kernel.org>
Suggested-by: Leon Romanovsky <leon@kernel.org>
Suggested-by: Greg KH <gregkh@linuxfoundation.org>
Reviewed-by: Leon Romanovsky <leon@kernel.org>
Reviewed-by: Shuah Khan <skhan@linuxfoundation.org>
Signed-off-by: Willy Tarreau <w@1wt.eu>
Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260509094755.2838-3-w@1wt.eu>
Pull documentation updates from Jonathan Corbet:
"A slightly calmer cycle for docs this time around, though there is
still a fair amount going on, including:
- Some signs of life on the long-moribund Japanese translation
- Documentation on policies around the use of generative tools for
patch submissions, and a separate document intended for consumption
by generative tools
- The completion of the move of the documentation tools to
tools/docs. For now we're leaving a /scripts/kernel-doc symlink
behind to avoid breaking scripts
- Ongoing build-system work includes the incorporation of
documentation in Python code, better support for documenting
variables, and lots of improvements and fixes
- Automatic linking of man-page references -- cat(1), for example --
to the online pages in the HTML build
...and the usual array of typo fixes and such"
* tag 'docs-7.0' of git://git.kernel.org/pub/scm/linux/kernel/git/docs/linux: (107 commits)
doc: development-process: add notice on testing
tools: sphinx-build-wrapper: improve its help message
docs: sphinx-build-wrapper: allow -v override -q
docs: kdoc: Fix pdfdocs build for tools
docs: ja_JP: process: translate 'Obtain a current source tree'
docs: fix 're-use' -> 'reuse' in documentation
docs: ioctl-number: fix a typo in ioctl-number.rst
docs: filesystems: ensure proc pid substitutable is complete
docs: automarkup.py: Skip common English words as C identifiers
Documentation: use a source-read extension for the index link boilerplate
docs: parse_features: make documentation more consistent
docs: add parse_features module documentation
docs: jobserver: do some documentation improvements
docs: add jobserver module documentation
docs: kabi: helpers: add documentation for each "enum" value
docs: kabi: helpers: add helper for debug bits 7 and 8
docs: kabi: system_symbols: end docstring phrases with a dot
docs: python: abi_regex: do some improvements at documentation
docs: python: abi_parser: do some improvements at documentation
docs: add kabi modules documentation
...
The root document usually has a special :ref:`genindex` link to the
generated index. This is also the case for Documentation/index.rst. The
other index.rst files deeper in the directory hierarchy usually don't.
For SPHINXDIRS builds, the root document isn't Documentation/index.rst,
but some other index.rst in the hierarchy. Currently they have a
".. only::" block to add the index link when doing SPHINXDIRS html
builds.
This is obviously very tedious and repetitive. The link is also added to
all index.rst files in the hierarchy for SPHINXDIRS builds, not just the
root document.
Put the boilerplate in a sphinx-includes/subproject-index.rst file, and
include it at the end of the root document for subproject builds in an
ad-hoc source-read extension defined in conf.py.
For now, keep having the boilerplate in translations, because this
approach currently doesn't cover translated index link headers.
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
Cc: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Tested-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
[jc: did s/doctree/kern_doc_dir/ ]
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260123143149.2024303-1-jani.nikula@intel.com>
In the last few years, the capabilities of coding tools have exploded.
As those capabilities have expanded, contributors and maintainers have
more and more questions about how and when to apply those
capabilities.
Add new Documentation to guide contributors on how to best use kernel
development tools, new and old.
Note, though, there are fundamentally no new or unique rules in this
new document. It clarifies expectations that the kernel community has
had for many years. For example, researchers are already asked to
disclose the tools they use to find issues by
Documentation/process/researcher-guidelines.rst. This new document
just reiterates existing best practices for development tooling.
In short: Please show your work and make sure your contribution is
easy to review.
Signed-off-by: Dave Hansen <dave.hansen@linux.intel.com>
Reviewed-by: Shuah Khan <shuah@kernel.org>
Reviewed-by: Kees Cook <kees@kernel.org>
Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Reviewed-by: Miguel Ojeda <ojeda@kernel.org>
Reviewed-by: Luis Chamberlain <mcgrof@kernel.org>
Reviewed-by: SeongJae Park <sj@kernel.org>
Reviewed-by: Dan Williams <dan.j.williams@intel.com>
Reviewed-by: Steven Rostedt <rostedt@goodmis.org>
Reviewed-by: Paul E. McKenney <paulmck@kernel.org>
Reviewed-by: Simon Glass <simon.glass@canonical.com>
Reviewed-by: Lee Jones <lee@kernel.org>
Reviewed-by: Lorenzo Stoakes <lorenzo.stoakes@oracle.com>
Cc: NeilBrown <neilb@ownmail.net>
Cc: Lorenzo Stoakes <lorenzo.stoakes@oracle.com>
Cc: Dan Williams <dan.j.williams@intel.com>
Cc: Theodore Ts'o <tytso@mit.edu>
Cc: Sasha Levin <sashal@kernel.org>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Vlastimil Babka <vbabka@suse.cz>
Cc: workflows@vger.kernel.org
Cc: ksummit@lists.linux.dev
Link: https://lore.kernel.org/all/cfb8bb96-e798-474d-bc6f-9cf610fe720f@lucifer.local/
--
Changes from v5:
* Add more review tags
* Add a blurb to the "special" asks bullet to mention that extra
testing may be requested.
* Reword the closing paragraph of "Out of Scope" section for clarity
* Remove an "AI" and make small wording tweak (Jon)
Changes from v4:
* Modest tweaking and rewording to strengthen language
* Add a section to help alleviate concerns that the document would
not enable maintainers to act forcefully enough in the face of
high-volume low-quality contributions (aka. AI slop).
This is very close to some text that Lorenzo posted. I just
made some very minor wording tweaks and spelling fixes.
* Note: v4 mistakenly had "v3" in the subject
Changes from v3:
* Wording/formatting tweaks (Randy)
Changes from v2:
* Mention testing (Shuah)
* Remove "very", rename LLM => coding assistant (Dan)
* More formatting sprucing up and minor typos (Miguel)
* Make changelog and text less flashy (Christian)
* Tone down critical=>helpful (Neil)
Changes from v1:
* Rename to generated-content.rst and add to documentation index.
(Jon)
* Rework subject to align with the new filename
* Replace commercial names with generic ones. (Jon)
* Be consistent about punctuation at the end of bullets for whole
sentences. (Miguel)
* Formatting sprucing up and minor typos (Miguel)
This document was a collaborative effort from all the members of
the TAB. I just reformatted it into .rst and wrote the changelog.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260119200418.89541-1-dave.hansen@linux.intel.com>
Add guidance for AI assistants and developers using AI tools for kernel
contributions, per the consensus reached at the 2025 Maintainers Summit.
Create Documentation/process/coding-assistants.rst with detailed guidance
on licensing, Signed-off-by requirements, and attribution format. The
README points AI tools to this documentation.
This will allow coding assistants to easily parse these instructions and
comply with guidelines set by the community.
Link: https://lwn.net/Articles/1049830/
Signed-off-by: Sasha Levin <sashal@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20251223122110.2496946-1-sashal@kernel.org>
This idea was formed after noticing that new developers experience
certain difficulty to navigate within the multitude of different
debugging options in the Kernel and while there often is good
documentation for the tools, the developer has to know first that they
exist and where to find them.
Add a general debugging section to the Kernel documentation, as an
easily locatable entry point to other documentation and as a general
guideline for the topic.
Signed-off-by: Sebastian Fricke <sebastian.fricke@collabora.com>
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20241028-media_docs_improve_v3-v3-1-edf5c5b3746f@collabora.com
'patch-acceptance' on 'Other material' section of 'process/index', which
is for unsorted documents, is actually well organized under
'arch/riscv/' directory, and linked on the index document of the
directory. Remove it from the 'Other material' section.
Signed-off-by: SeongJae Park <sj@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20240624185312.94537-3-sj@kernel.org
'unaligned-memory-access document' is linked on 'Other material' section
of 'core-api/index', which is for unsorted documents. But it is
actually well organized under 'core-api/' directory, and linked on the
'core-api/index'. Remove it from 'Other material' section of
'process/index' document.
Signed-off-by: SeongJae Park <sj@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20240624185312.94537-2-sj@kernel.org
The process book is arguably the most important documentation we have; the
top three trafficked pages on docs.kernel.org are found here. Make a
beginning effort to impose a more useful organization on this page to ease
developers into the community.
Acked-by: Vegard Nossum <vegard.nossum@oracle.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Pull documentation updates from Jonathan Corbet:
"Commit volume in documentation is relatively low this time, but there
is still a fair amount going on, including:
- Reorganize the architecture-specific documentation under
Documentation/arch
This makes the structure match the source directory and helps to
clean up the mess that is the top-level Documentation directory a
bit. This work creates the new directory and moves x86 and most of
the less-active architectures there.
The current plan is to move the rest of the architectures in 6.5,
with the patches going through the appropriate subsystem trees.
- Some more Spanish translations and maintenance of the Italian
translation
- A new "Kernel contribution maturity model" document from Ted
- A new tutorial on quickly building a trimmed kernel from Thorsten
Plus the usual set of updates and fixes"
* tag 'docs-6.4' of git://git.lwn.net/linux: (47 commits)
media: Adjust column width for pdfdocs
media: Fix building pdfdocs
docs: clk: add documentation to log which clocks have been disabled
docs: trace: Fix typo in ftrace.rst
Documentation/process: always CC responsible lists
docs: kmemleak: adjust to config renaming
ELF: document some de-facto PT_* ABI quirks
Documentation: arm: remove stih415/stih416 related entries
docs: turn off "smart quotes" in the HTML build
Documentation: firmware: Clarify firmware path usage
docs/mm: Physical Memory: Fix grammar
Documentation: Add document for false sharing
dma-api-howto: typo fix
docs: move m68k architecture documentation under Documentation/arch/
docs: move parisc documentation under Documentation/arch/
docs: move ia64 architecture docs under Documentation/arch/
docs: Move arc architecture docs under Documentation/arch/
docs: move nios2 documentation under Documentation/arch/
docs: move openrisc documentation under Documentation/arch/
docs: move superh documentation under Documentation/arch/
...
Commit 31b24bee33 ("docs: add a warning to submitting-drivers.rst")
in October 2016 already warns "This (...) should maybe just be deleted,
but I'm not quite ready to do that yet".
Maybe, six years ago, we were not ready but let us remove old content
for the better now and structure and maintain less content in the kernel
documentation with a better result.
Drop this already outdated document and adjust all textual references.
Here is an argument why deleting the content will not remove any useful
information to the existing kernel documentation, individually broken down
for each section.
Section "Allocating Device Numbers" refers to https://www.lanana.org/, and
then refers to Documentation/admin-guide/devices.rst.
However, the devices.rst clearly states:
"The version of this document at lanana.org is no longer maintained."
Everything needed for submitting drivers is already stated in devices.rst
and the reference to https://www.lanana.org/ is outdated, and should be
just deleted.
Section "Who To Submit Drivers To" is all about Linux 2.0 - 2.6, before
the new release version scheme; the mentioned developers are still around,
but actually not the first developers to contact anymore.
Section "What Criteria Determine Acceptance" has a few bullet points:
Licensing and Copyright is well-covered in process/kernel-license.rst.
Interfaces, Code, Portability, Clarity state some obvious things about
ensuring kernel code quality.
Control suggests to add a MAINTAINERS entry, which is already mentioned in
6.Followthrough.rst: "... added yourself to the MAINTAINERS file..."
PM support states a bit about implementing and testing power management of
a driver, it remains an open question where to place that in the process
documents. Driver developers interested in power management will find the
corresponding part on power management in the kernel documentation anyway.
In section "What Criteria Do Not Determine Acceptance", the points Vendor
and Author states something basic consequence of the kernel being an
open-source community software development. Probably no need to mention it
nowadays.
Section "Resources" lists resources that are also mentioned elsewhere more
central.
- Linux kernel tree and mailing list is mentioned in many places.
- https://lwn.net/Kernel/LDD3/ is mentioned in
Documentation/process/kernel-docs.rst.
- https://lwn.net/ is mentioned in:
- Documentation/process/8.Conclusion.rst
- Documentation/process/kernel-docs.rst
- https://kernelnewbies.org/ is mentioned in:
- Documentation/process/8.Conclusion.rst
- Documentation/process/kernel-docs.rst
- http://www.linux-usb.org/ is mentioned in
Documentation/driver-api/usb/usb.rst
- https://landley.net/kdocs/ols/2002/ols2002-pages-545-555.pdf
is mentioned in Documentation/process/kernel-docs.rst
- https://kernelnewbies.org/KernelJanitors is mentioned in
Documentation/process/howto.rst
- https://git-scm.com/ is mentioned in
- Documentation/process/2.Process.rst
- Documentation/process/7.AdvancedTopics.rst
- Documentation/process/howto.rst
Signed-off-by: Lukas Bulwahn <lukas.bulwahn@gmail.com>
Link: https://lore.kernel.org/r/20220704122537.3407-7-lukas.bulwahn@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Create two documents explaining various aspects around regression
handling and tracking; one is aimed at users, the other targets
developers.
The texts among others describes the first rule of Linux kernel
development and what it means in practice. They also explain what a
regression actually is and how to report one properly.
Both texts additionally provide a brief introduction to the bot the
kernel's regression tracker uses to facilitate the work, but mention the
use is optional.
To sum things up, provide a few quotes from Linus in the document for
developers to show how serious we take regressions.
Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
Link: https://lore.kernel.org/r/34e56d3588f22d7e0b4d635ef9c9c3b33ca4ac04.1644994117.git.linux@leemhuis.info
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
General rules for patch submission, coding style and related details are
available, but most subsystems have their subsystem-specific extra rules
which differ or go beyond the common rules.
Mark suggested to add a subsystem/maintainer handbook section, where
subsystem maintainers can explain their specific quirks.
Add the section and link to it from the submitting-patches document.
[ bp: Add a SPDX identifier. ]
Suggested-by: Mark Brown <broonie@kernel.org>
Signed-off-by: Thomas Gleixner <tglx@linutronix.de>
Signed-off-by: Borislav Petkov <bp@suse.de>
Link: https://lkml.kernel.org/r/20181107171149.074948887@linutronix.de
Link: https://lore.kernel.org/r/20210913153942.15251-2-bp@alien8.de
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
