From 197bbebd25810c5218e3347d61641be8e49c5404 Mon Sep 17 00:00:00 2001 From: Andy Shevchenko Date: Wed, 26 Nov 2025 22:46:07 +0100 Subject: docs: Update documentation to avoid mentioning of kernel.h For several years, and still ongoing, the kernel.h is being split to smaller and narrow headers to avoid "including everything" approach which is bad in many ways. Since that, documentation missed a few required updates to align with that work. Do it here. Note, language translations are left untouched and if anybody willing to help, please provide path(es) based on the updated English variant. Signed-off-by: Andy Shevchenko Reviewed-by: Randy Dunlap Reviewed-by: Mathieu Poirier Tested-by: Randy Dunlap Signed-off-by: Jonathan Corbet Message-ID: <20251126214709.2322314-1-andriy.shevchenko@linux.intel.com> --- Documentation/process/coding-style.rst | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) (limited to 'Documentation/process') diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst index 2969ca378dbb..258158637f65 100644 --- a/Documentation/process/coding-style.rst +++ b/Documentation/process/coding-style.rst @@ -1070,7 +1070,7 @@ readability. 18) Don't re-invent the kernel macros ------------------------------------- -The header file include/linux/kernel.h contains a number of macros that +There are many header files in include/linux/ that contain a number of macros that you should use, rather than explicitly coding some variant of them yourself. For example, if you need to calculate the length of an array, take advantage of the macro @@ -1079,14 +1079,18 @@ of the macro #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0])) +which is defined in array_size.h. + Similarly, if you need to calculate the size of some structure member, use .. code-block:: c #define sizeof_field(t, f) (sizeof(((t*)0)->f)) -There are also min() and max() macros that do strict type checking if you -need them. Feel free to peruse that header file to see what else is already +which is defined in stddef.h. + +There are also min() and max() macros defined in minmax.h that do strict type checking +if you need them. Feel free to peruse the header files to see what else is already defined that you shouldn't reproduce in your code. -- cgit v1.2.3 From 273aa250f138c996f351be4a2556043ec8bbc9a5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Uwe=20Kleine-K=C3=B6nig?= Date: Wed, 3 Dec 2025 08:43:47 +0100 Subject: Documentation: Improve wording on requirements for a free Nitrokey MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit "listed in MAINTAINERS" is not enough to qualify for the free Nitrokey Start. You have to be listed in an M: entry. Mention that to reduce confusion for reviewers who wonder why their application fails. Signed-off-by: Uwe Kleine-König Reviewed-by: Konstantin Ryabitsev Signed-off-by: Jonathan Corbet Message-ID: <20251203074349.1826233-2-u.kleine-koenig@baylibre.com> --- Documentation/process/maintainer-pgp-guide.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'Documentation/process') diff --git a/Documentation/process/maintainer-pgp-guide.rst b/Documentation/process/maintainer-pgp-guide.rst index b6919bf606c3..2e4da3de25d4 100644 --- a/Documentation/process/maintainer-pgp-guide.rst +++ b/Documentation/process/maintainer-pgp-guide.rst @@ -405,8 +405,8 @@ geographical region, and open/proprietary hardware considerations. .. note:: - If you are listed in MAINTAINERS or have an account at kernel.org, - you `qualify for a free Nitrokey Start`_ courtesy of The Linux + If you are listed in an `M:` entry in MAINTAINERS or have an account at + kernel.org, you `qualify for a free Nitrokey Start`_ courtesy of The Linux Foundation. .. _`Nitrokey Start`: https://www.nitrokey.com/products/nitrokeys -- cgit v1.2.3 From ceddb2c001d9f22fd3712dc0425c3a15bc504461 Mon Sep 17 00:00:00 2001 From: Willy Tarreau Date: Sat, 29 Nov 2025 15:17:41 +0100 Subject: Documentation: insist on the plain-text requirement for security reports As the trend of AI-generated reports is growing, the trend of unreadable reports in gimmicky formats is following, and we cannot request that developers rely on online viewers to be able to read a security report full for formatting tags. Let's just insist on the plain text requirement a bit more. Signed-off-by: Willy Tarreau Signed-off-by: Ingo Molnar Reviewed-by: Greg Kroah-Hartman Signed-off-by: Jonathan Corbet Message-ID: <20251129141741.19046-1-w@1wt.eu> --- Documentation/process/security-bugs.rst | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) (limited to 'Documentation/process') diff --git a/Documentation/process/security-bugs.rst b/Documentation/process/security-bugs.rst index 84657e7d2e5b..c0cf93e11565 100644 --- a/Documentation/process/security-bugs.rst +++ b/Documentation/process/security-bugs.rst @@ -33,12 +33,16 @@ that can speed up the process considerably. It is possible that the security team will bring in extra help from area maintainers to understand and fix the security vulnerability. -Please send plain text emails without attachments where possible. +Please send **plain text** emails without attachments where possible. It is much harder to have a context-quoted discussion about a complex issue if all the details are hidden away in attachments. Think of it like a :doc:`regular patch submission <../process/submitting-patches>` (even if you don't have a patch yet): describe the problem and impact, list reproduction steps, and follow it with a proposed fix, all in plain text. +Markdown, HTML and RST formatted reports are particularly frowned upon since +they're quite hard to read for humans and encourage to use dedicated viewers, +sometimes online, which by definition is not acceptable for a confidential +security report. Disclosure and embargoed information ------------------------------------ -- cgit v1.2.3 From 4971ca2007e3858171982c286421ac1af1d624a9 Mon Sep 17 00:00:00 2001 From: Vincent Mailhol Date: Fri, 26 Dec 2025 00:46:48 +0100 Subject: docs: process: email-client: add Thunderbird "Toggle Line Wrap" extension MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit While reading the git-format-patch manpages [1], I discovered the existence of the "Toggle Line Wrap" extension for Thunderbird which I found rather convenient. Looking at the history, the ancestor of this extension was added to the documentation in commit e0e34e977a7c ("Documentation/email-clients.txt: update Thunderbird docs with wordwrap plugin") but then removed in commit f9a0974d3f70 ("Documentation: update thunderbird email client settings"). Extend the paragraph on Thunderbird's mailnews.wraplength register to mention the existence of the "Toggle Line Wrap" extension. The goal is not to create a war on what is the best option so make it clear that this is just an alternative. [1] man git-format-patch -- §Thunderbird Link: https://git-scm.com/docs/git-format-patch#_thunderbird Signed-off-by: Vincent Mailhol Reviewed-by: Gal Pressman Acked-by: Sotir Danailov # As past commit author Acked-by: Randy Dunlap Tested-by: Randy Dunlap Signed-off-by: Jonathan Corbet Message-ID: <20251226-docs_thunderbird-toggle-line-wrap-v2-1-aebb8c60025d@kernel.org> --- Documentation/process/email-clients.rst | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) (limited to 'Documentation/process') diff --git a/Documentation/process/email-clients.rst b/Documentation/process/email-clients.rst index 84a2450bb6ec..b5377630a648 100644 --- a/Documentation/process/email-clients.rst +++ b/Documentation/process/email-clients.rst @@ -324,7 +324,14 @@ To beat some sense out of the internal editor, do this: - Set ``mailnews.send_plaintext_flowed`` to ``false`` - - Set ``mailnews.wraplength`` from ``72`` to ``0`` + - Set ``mailnews.wraplength`` from ``72`` to ``0`` **or** install the + "Toggle Line Wrap" extension + + https://github.com/jan-kiszka/togglelinewrap + + https://addons.thunderbird.net/thunderbird/addon/toggle-line-wrap + + to control this registry on the fly. - Don't write HTML messages! Go to the main window :menuselection:`Main Menu-->Account Settings-->youracc@server.something-->Composition & Addressing`! -- cgit v1.2.3 From 5ce70894f6cade9dc4d7c2a376724c0d8083ff8a Mon Sep 17 00:00:00 2001 From: Volodymyr Kot Date: Thu, 25 Dec 2025 13:39:11 +0000 Subject: Doc: correct spelling and wording mistakes Fixed capitalization and punctuation in process documentation. Signed-off-by: Volodymyr Kot Signed-off-by: Jonathan Corbet Message-ID: <20251225133911.87512-1-volodymyr.kot.ua@gmail.com> --- Documentation/process/1.Intro.rst | 2 +- Documentation/process/2.Process.rst | 2 +- Documentation/process/4.Coding.rst | 6 +++--- Documentation/process/7.AdvancedTopics.rst | 2 +- 4 files changed, 6 insertions(+), 6 deletions(-) (limited to 'Documentation/process') diff --git a/Documentation/process/1.Intro.rst b/Documentation/process/1.Intro.rst index 25ca49f7ae4d..2c93caea069f 100644 --- a/Documentation/process/1.Intro.rst +++ b/Documentation/process/1.Intro.rst @@ -194,7 +194,7 @@ include: are cloudy at best; quite a few kernel copyright holders believe that most binary-only modules are derived products of the kernel and that, as a result, their distribution is a violation of the GNU General Public - license (about which more will be said below). Your author is not a + License (about which more will be said below). Your author is not a lawyer, and nothing in this document can possibly be considered to be legal advice. The true legal status of closed-source modules can only be determined by the courts. But the uncertainty which haunts those modules diff --git a/Documentation/process/2.Process.rst b/Documentation/process/2.Process.rst index 7bd41838a546..57fa8cac58a6 100644 --- a/Documentation/process/2.Process.rst +++ b/Documentation/process/2.Process.rst @@ -3,7 +3,7 @@ How the development process works ================================= -Linux kernel development in the early 1990's was a pretty loose affair, +Linux kernel development in the early 1990s was a pretty loose affair, with relatively small numbers of users and developers involved. With a user base in the millions and with some 2,000 developers involved over the course of one year, the kernel has since had to evolve a number of diff --git a/Documentation/process/4.Coding.rst b/Documentation/process/4.Coding.rst index 80bcc1cabc23..c0f57d0c4f73 100644 --- a/Documentation/process/4.Coding.rst +++ b/Documentation/process/4.Coding.rst @@ -160,12 +160,12 @@ irrelevant. Locking ******* -In May, 2006, the "Devicescape" networking stack was, with great +In May 2006, the "Devicescape" networking stack was, with great fanfare, released under the GPL and made available for inclusion in the mainline kernel. This donation was welcome news; support for wireless networking in Linux was considered substandard at best, and the Devicescape stack offered the promise of fixing that situation. Yet, this code did not -actually make it into the mainline until June, 2007 (2.6.22). What +actually make it into the mainline until June 2007 (2.6.22). What happened? This code showed a number of signs of having been developed behind @@ -204,7 +204,7 @@ regression in the first place. It is often argued that a regression can be justified if it causes things to work for more people than it creates problems for. Why not make a change if it brings new functionality to ten systems for each one it -breaks? The best answer to this question was expressed by Linus in July, +breaks? The best answer to this question was expressed by Linus in July 2007: :: diff --git a/Documentation/process/7.AdvancedTopics.rst b/Documentation/process/7.AdvancedTopics.rst index 43291704338e..185651d87f2a 100644 --- a/Documentation/process/7.AdvancedTopics.rst +++ b/Documentation/process/7.AdvancedTopics.rst @@ -53,7 +53,7 @@ When you are ready to start putting up git trees for others to look at, you will, of course, need a server that can be pulled from. Setting up such a server with git-daemon is relatively straightforward if you have a system which is accessible to the Internet. Otherwise, free, public hosting sites -(Github, for example) are starting to appear on the net. Established +(GitHub, for example) are starting to appear on the net. Established developers can get an account on kernel.org, but those are not easy to come by; see https://kernel.org/faq/ for more information. -- cgit v1.2.3 From 8a12e3fbf2c30cc66bb0be1363c08aca1d33e80a Mon Sep 17 00:00:00 2001 From: SeongJae Park Date: Wed, 24 Dec 2025 17:54:45 -0800 Subject: docs: submitting-patches: suggest adding previous version links For review of patches that revisioned multiple times, patch changelogs are very useful. Adding actual links to the previous versions can further help the review. Using such links, reviewers can double check the changelog by themselves, and find previous discussions. Nowadays having such links (e.g., lore.kernel.org archive links) is easy and reliable. Suggest adding such links if available. Signed-off-by: SeongJae Park Signed-off-by: Jonathan Corbet Message-ID: <20251225015447.16387-1-sj@kernel.org> --- Documentation/process/submitting-patches.rst | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) (limited to 'Documentation/process') diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst index 9a509f1a6873..e69d19ad658f 100644 --- a/Documentation/process/submitting-patches.rst +++ b/Documentation/process/submitting-patches.rst @@ -805,7 +805,8 @@ not part of the changelog which gets committed to the git tree. It is additional information for the reviewers. If it's placed above the commit tags, it needs manual interaction to remove it. If it is below the separator line, it gets automatically stripped off when applying the -patch:: +patch. If available, adding links to previous versions of the patch (e.g., +lore.kernel.org archive link) is recommended to help reviewers:: ... @@ -814,6 +815,9 @@ patch:: V2 -> V3: Removed redundant helper function V1 -> V2: Cleaned up coding style and addressed review comments + v2: https://lore.kernel.org/bar + v1: https://lore.kernel.org/foo + path/to/file | 5+++-- ... -- cgit v1.2.3 From 78d979db6cef557c171d6059cbce06c3db89c7ee Mon Sep 17 00:00:00 2001 From: Sasha Levin Date: Tue, 23 Dec 2025 07:21:10 -0500 Subject: docs: add AI Coding Assistants documentation 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 Signed-off-by: Jonathan Corbet Message-ID: <20251223122110.2496946-1-sashal@kernel.org> --- Documentation/process/coding-assistants.rst | 59 +++++++++++++++++++++++++++++ Documentation/process/index.rst | 1 + 2 files changed, 60 insertions(+) create mode 100644 Documentation/process/coding-assistants.rst (limited to 'Documentation/process') diff --git a/Documentation/process/coding-assistants.rst b/Documentation/process/coding-assistants.rst new file mode 100644 index 000000000000..899f4459c52d --- /dev/null +++ b/Documentation/process/coding-assistants.rst @@ -0,0 +1,59 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _coding_assistants: + +AI Coding Assistants +++++++++++++++++++++ + +This document provides guidance for AI tools and developers using AI +assistance when contributing to the Linux kernel. + +AI tools helping with Linux kernel development should follow the standard +kernel development process: + +* Documentation/process/development-process.rst +* Documentation/process/coding-style.rst +* Documentation/process/submitting-patches.rst + +Licensing and Legal Requirements +================================ + +All contributions must comply with the kernel's licensing requirements: + +* All code must be compatible with GPL-2.0-only +* Use appropriate SPDX license identifiers +* See Documentation/process/license-rules.rst for details + +Signed-off-by and Developer Certificate of Origin +================================================= + +AI agents MUST NOT add Signed-off-by tags. Only humans can legally +certify the Developer Certificate of Origin (DCO). The human submitter +is responsible for: + +* Reviewing all AI-generated code +* Ensuring compliance with licensing requirements +* Adding their own Signed-off-by tag to certify the DCO +* Taking full responsibility for the contribution + +Attribution +=========== + +When AI tools contribute to kernel development, proper attribution +helps track the evolving role of AI in the development process. +Contributions should include an Assisted-by tag in the following format:: + + Assisted-by: AGENT_NAME:MODEL_VERSION [TOOL1] [TOOL2] + +Where: + +* ``AGENT_NAME`` is the name of the AI tool or framework +* ``MODEL_VERSION`` is the specific model version used +* ``[TOOL1] [TOOL2]`` are optional specialized analysis tools used + (e.g., coccinelle, sparse, smatch, clang-tidy) + +Basic development tools (git, gcc, make, editors) should not be listed. + +Example:: + + Assisted-by: Claude:claude-3-opus coccinelle sparse diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst index aa12f2660194..d18eacbf2c53 100644 --- a/Documentation/process/index.rst +++ b/Documentation/process/index.rst @@ -68,6 +68,7 @@ beyond). stable-kernel-rules management-style researcher-guidelines + coding-assistants Dealing with bugs ----------------- -- cgit v1.2.3 From 8913632998fcda1793d04fd4ae2327b4bee9b106 Mon Sep 17 00:00:00 2001 From: Nauman Sabir Date: Fri, 16 Jan 2026 00:01:10 +0100 Subject: Documentation: Fix typos and grammatical errors Fix various typos and grammatical errors across documentation files: - Fix missing preposition 'in' in process/changes.rst - Correct 'result by' to 'result from' in admin-guide/README.rst - Fix 'before hand' to 'beforehand' in cgroup-v1/hugetlb.rst - Correct 'allows to limit' to 'allows limiting' in hugetlb.rst, cgroup-v2.rst, and kconfig-language.rst - Fix 'needs precisely know' to 'needs to precisely know' - Correct 'overcommited' to 'overcommitted' in hugetlb.rst - Fix subject-verb agreement: 'never causes' to 'never cause' - Fix 'there is enough' to 'there are enough' in hugetlb.rst - Fix 'metadatas' to 'metadata' in filesystems/erofs.rst - Fix 'hardwares' to 'hardware' in scsi/ChangeLog.sym53c8xx Signed-off-by: Nauman Sabir Acked-by: Tejun Heo Message-ID: <20260115230110.7734-1-officialnaumansabir@gmail.com> Signed-off-by: Jonathan Corbet --- Documentation/process/changes.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/process') diff --git a/Documentation/process/changes.rst b/Documentation/process/changes.rst index 62951cdb13ad..0cf97dbab29d 100644 --- a/Documentation/process/changes.rst +++ b/Documentation/process/changes.rst @@ -218,7 +218,7 @@ DevFS has been obsoleted in favour of udev Linux documentation for functions is transitioning to inline documentation via specially-formatted comments near their definitions in the source. These comments can be combined with ReST -files the Documentation/ directory to make enriched documentation, which can +files in the Documentation/ directory to make enriched documentation, which can then be converted to PostScript, HTML, LaTex, ePUB and PDF files. In order to convert from ReST format to a format of your choice, you'll need Sphinx. -- cgit v1.2.3 From e5b1c0fa4ff21185b29fd4202407bbde37478c91 Mon Sep 17 00:00:00 2001 From: Petr Vorel Date: Tue, 13 Jan 2026 12:36:08 +0100 Subject: Documentation: Remove :manpage: from non-existing man pages Removing :manpage: from non-existing man pages (xyzzy(2), xyzzyat(2), fxyzzy(3) in adding-syscalls.rst, including translations) prevent adding link to nonexisting man pages when using manpages_url in next commit. While at it, add also missing '(2)' in sp_SP translation. Reviewed-by: Alejandro Colomar Signed-off-by: Petr Vorel Signed-off-by: Jonathan Corbet Message-ID: <20260113113612.315748-2-pvorel@suse.cz> --- Documentation/process/adding-syscalls.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) (limited to 'Documentation/process') diff --git a/Documentation/process/adding-syscalls.rst b/Documentation/process/adding-syscalls.rst index fc0b0bbcd34d..e8892f03eadd 100644 --- a/Documentation/process/adding-syscalls.rst +++ b/Documentation/process/adding-syscalls.rst @@ -111,7 +111,7 @@ should use a file descriptor as the handle for that object -- don't invent a new type of userspace object handle when the kernel already has mechanisms and well-defined semantics for using file descriptors. -If your new :manpage:`xyzzy(2)` system call does return a new file descriptor, +If your new xyzzy(2) system call does return a new file descriptor, then the flags argument should include a value that is equivalent to setting ``O_CLOEXEC`` on the new FD. This makes it possible for userspace to close the timing window between ``xyzzy()`` and calling @@ -127,18 +127,18 @@ descriptor. Making a file descriptor ready for reading or writing is the normal way for the kernel to indicate to userspace that an event has occurred on the corresponding kernel object. -If your new :manpage:`xyzzy(2)` system call involves a filename argument:: +If your new xyzzy(2) system call involves a filename argument:: int sys_xyzzy(const char __user *path, ..., unsigned int flags); -you should also consider whether an :manpage:`xyzzyat(2)` version is more appropriate:: +you should also consider whether an xyzzyat(2) version is more appropriate:: int sys_xyzzyat(int dfd, const char __user *path, ..., unsigned int flags); This allows more flexibility for how userspace specifies the file in question; in particular it allows userspace to request the functionality for an already-opened file descriptor using the ``AT_EMPTY_PATH`` flag, effectively -giving an :manpage:`fxyzzy(3)` operation for free:: +giving an fxyzzy(3) operation for free:: - xyzzyat(AT_FDCWD, path, ..., 0) is equivalent to xyzzy(path,...) - xyzzyat(fd, "", ..., AT_EMPTY_PATH) is equivalent to fxyzzy(fd, ...) @@ -147,11 +147,11 @@ giving an :manpage:`fxyzzy(3)` operation for free:: :manpage:`openat(2)` man page; for an example of AT_EMPTY_PATH, see the :manpage:`fstatat(2)` man page.) -If your new :manpage:`xyzzy(2)` system call involves a parameter describing an +If your new xyzzy(2) system call involves a parameter describing an offset within a file, make its type ``loff_t`` so that 64-bit offsets can be supported even on 32-bit architectures. -If your new :manpage:`xyzzy(2)` system call involves privileged functionality, +If your new xyzzy(2) system call involves privileged functionality, it needs to be governed by the appropriate Linux capability bit (checked with a call to ``capable()``), as described in the :manpage:`capabilities(7)` man page. Choose an existing capability bit that governs related functionality, @@ -160,7 +160,7 @@ under the same bit, as this goes against capabilities' purpose of splitting the power of root. In particular, avoid adding new uses of the already overly-general ``CAP_SYS_ADMIN`` capability. -If your new :manpage:`xyzzy(2)` system call manipulates a process other than +If your new xyzzy(2) system call manipulates a process other than the calling process, it should be restricted (using a call to ``ptrace_may_access()``) so that only a calling process with the same permissions as the target process, or with the necessary capabilities, can @@ -196,7 +196,7 @@ be cc'ed to linux-api@vger.kernel.org. Generic System Call Implementation ---------------------------------- -The main entry point for your new :manpage:`xyzzy(2)` system call will be called +The main entry point for your new xyzzy(2) system call will be called ``sys_xyzzy()``, but you add this entry point with the appropriate ``SYSCALL_DEFINEn()`` macro rather than explicitly. The 'n' indicates the number of arguments to the system call, and the macro takes the system call name -- cgit v1.2.3 From a66437c27979577fe1feffba502b9eadff13af7d Mon Sep 17 00:00:00 2001 From: Dave Hansen Date: Mon, 19 Jan 2026 12:04:18 -0800 Subject: Documentation: Provide guidelines for tool-generated content 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 Reviewed-by: Shuah Khan Reviewed-by: Kees Cook Reviewed-by: Greg Kroah-Hartman Reviewed-by: Miguel Ojeda Reviewed-by: Luis Chamberlain Reviewed-by: SeongJae Park Reviewed-by: Dan Williams Reviewed-by: Steven Rostedt Reviewed-by: Paul E. McKenney Reviewed-by: Simon Glass Reviewed-by: Lee Jones Reviewed-by: Lorenzo Stoakes Cc: NeilBrown Cc: Lorenzo Stoakes Cc: Dan Williams Cc: Theodore Ts'o Cc: Sasha Levin Cc: Jonathan Corbet Cc: Vlastimil Babka 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 Message-ID: <20260119200418.89541-1-dave.hansen@linux.intel.com> --- Documentation/process/generated-content.rst | 109 ++++++++++++++++++++++++++++ Documentation/process/index.rst | 1 + 2 files changed, 110 insertions(+) create mode 100644 Documentation/process/generated-content.rst (limited to 'Documentation/process') diff --git a/Documentation/process/generated-content.rst b/Documentation/process/generated-content.rst new file mode 100644 index 000000000000..08621e50a462 --- /dev/null +++ b/Documentation/process/generated-content.rst @@ -0,0 +1,109 @@ +============================================ +Kernel Guidelines for Tool-Generated Content +============================================ + +Purpose +======= + +Kernel contributors have been using tooling to generate contributions +for a long time. These tools can increase the volume of contributions. +At the same time, reviewer and maintainer bandwidth is a scarce +resource. Understanding which portions of a contribution come from +humans versus tools is helpful to maintain those resources and keep +kernel development healthy. + +The goal here is to clarify community expectations around tools. This +lets everyone become more productive while also maintaining high +degrees of trust between submitters and reviewers. + +Out of Scope +============ + +These guidelines do not apply to tools that make trivial tweaks to +preexisting content. Nor do they pertain to tooling that helps with +menial tasks. Some examples: + + - Spelling and grammar fix ups, like rephrasing to imperative voice + - Typing aids like identifier completion, common boilerplate or + trivial pattern completion + - Purely mechanical transformations like variable renaming + - Reformatting, like running Lindent, ``clang-format`` or + ``rust-fmt`` + +Even whenever your tool use is out of scope, you should still always +consider if it would help reviewing your contribution if the reviewer +knows about the tool that you used. + +In Scope +======== + +These guidelines apply when a meaningful amount of content in a kernel +contribution was not written by a person in the Signed-off-by chain, +but was instead created by a tool. + +Detection of a problem and testing the fix for it is also part of the +development process; if a tool was used to find a problem addressed by +a change, that should be noted in the changelog. This not only gives +credit where it is due, it also helps fellow developers find out about +these tools. + +Some examples: + - Any tool-suggested fix such as ``checkpatch.pl --fix`` + - Coccinelle scripts + - A chatbot generated a new function in your patch to sort list entries. + - A .c file in the patch was originally generated by a coding + assistant but cleaned up by hand. + - The changelog was generated by handing the patch to a generative AI + tool and asking it to write the changelog. + - The changelog was translated from another language. + +If in doubt, choose transparency and assume these guidelines apply to +your contribution. + +Guidelines +========== + +First, read the Developer's Certificate of Origin: +Documentation/process/submitting-patches.rst. Its rules are simple +and have been in place for a long time. They have covered many +tool-generated contributions. Ensure that you understand your entire +submission and are prepared to respond to review comments. + +Second, when making a contribution, be transparent about the origin of +content in cover letters and changelogs. You can be more transparent +by adding information like this: + + - What tools were used? + - The input to the tools you used, like the Coccinelle source script. + - If code was largely generated from a single or short set of + prompts, include those prompts. For longer sessions, include a + summary of the prompts and the nature of resulting assistance. + - Which portions of the content were affected by that tool? + - How is the submission tested and what tools were used to test the + fix? + +As with all contributions, individual maintainers have discretion to +choose how they handle the contribution. For example, they might: + + - Treat it just like any other contribution. + - Reject it outright. + - Treat the contribution specially, for example, asking for extra + testing, reviewing with extra scrutiny, or reviewing at a lower + priority than human-generated content. + - Ask for some other special steps, like asking the contributor to + elaborate on how the tool or model was trained. + - Ask the submitter to explain in more detail about the contribution + so that the maintainer can be assured that the submitter fully + understands how the code works. + - Suggest a better prompt instead of suggesting specific code changes. + +If tools permit you to generate a contribution automatically, expect +additional scrutiny in proportion to how much of it was generated. + +As with the output of any tooling, the result may be incorrect or +inappropriate. You are expected to understand and to be able to defend +everything you submit. If you are unable to do so, then do not submit +the resulting changes. + +If you do so anyway, maintainers are entitled to reject your series +without detailed review. diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst index d18eacbf2c53..9d1a73329007 100644 --- a/Documentation/process/index.rst +++ b/Documentation/process/index.rst @@ -68,6 +68,7 @@ beyond). stable-kernel-rules management-style researcher-guidelines + generated-content coding-assistants Dealing with bugs -- cgit v1.2.3 From 3c5fefc8f1c87ce5aad32b752abd1c0f4d25a39a Mon Sep 17 00:00:00 2001 From: junan Date: Fri, 16 Jan 2026 13:03:13 +0800 Subject: doc: kgdb: Add description about rodata=off kernel parameter STRICT_KERNEL_RWX can not be turned off throught menuconfig on some architectures, pass "rodata=off" to the kernel in this case. Tested with qemu on arm64. Signed-off-by: junan Suggested-by: Will Deacon Reviewed-by: Daniel Thompson (RISCstar) Signed-off-by: Jonathan Corbet Message-ID: <20260116050410.772340-2-junan76@163.com> --- Documentation/process/debugging/kgdb.rst | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'Documentation/process') diff --git a/Documentation/process/debugging/kgdb.rst b/Documentation/process/debugging/kgdb.rst index b29b0aac2717..f2c57de7992f 100644 --- a/Documentation/process/debugging/kgdb.rst +++ b/Documentation/process/debugging/kgdb.rst @@ -380,6 +380,13 @@ virtual address where the kernel image is mapped and confuses gdb which resolves addresses of kernel symbols from the symbol table of vmlinux. +Kernel parameter: ``rodata`` +---------------------------- + +``CONFIG_STRICT_KERNEL_RWX`` is turned on by default and is not +visible to menuconfig on some architectures (arm64 for example), +you can pass ``rodata=off`` to the kernel in this case. + Using kdb ========= -- cgit v1.2.3 From eba6ffd126cd52358181ed5a179644a161f9c65f Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Mon, 19 Jan 2026 13:05:01 +0100 Subject: docs: kdoc: move kernel-doc to tools/docs kernel-doc is the last documentation-related tool still living outside of the tools/docs directory; the time has come to move it over. [mchehab: fixed kdoc lib location] Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Message-ID: <311d17e403524349940a8b12de6b5e91e554b1f4.1768823489.git.mchehab+huawei@kernel.org> --- Documentation/process/coding-style.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/process') diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst index 258158637f65..35b381230f6e 100644 --- a/Documentation/process/coding-style.rst +++ b/Documentation/process/coding-style.rst @@ -614,7 +614,7 @@ it. When commenting the kernel API functions, please use the kernel-doc format. See the files at :ref:`Documentation/doc-guide/ ` and -``scripts/kernel-doc`` for details. Note that the danger of over-commenting +``tools/docs/kernel-doc`` for details. Note that the danger of over-commenting applies to kernel-doc comments all the same. Do not add boilerplate kernel-doc which simply reiterates what's obvious from the signature of the function. -- cgit v1.2.3 From a592a36e49372172d7c7551ec19ed18184c935e1 Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Fri, 23 Jan 2026 16:31:49 +0200 Subject: Documentation: use a source-read extension for the index link boilerplate 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 Cc: Mauro Carvalho Chehab Cc: Randy Dunlap Signed-off-by: Jani Nikula Tested-by: Mauro Carvalho Chehab Reviewed-by: Mauro Carvalho Chehab [jc: did s/doctree/kern_doc_dir/ ] Signed-off-by: Jonathan Corbet Message-ID: <20260123143149.2024303-1-jani.nikula@intel.com> --- Documentation/process/debugging/index.rst | 9 --------- Documentation/process/index.rst | 7 ------- 2 files changed, 16 deletions(-) (limited to 'Documentation/process') diff --git a/Documentation/process/debugging/index.rst b/Documentation/process/debugging/index.rst index 387d33d16f5e..357243e184e1 100644 --- a/Documentation/process/debugging/index.rst +++ b/Documentation/process/debugging/index.rst @@ -15,8 +15,6 @@ general guides kgdb userspace_debugging_guide -.. only:: subproject and html - subsystem specific guides ------------------------- @@ -25,13 +23,6 @@ subsystem specific guides media_specific_debugging_guide -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex` - General debugging advice ======================== diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst index 9d1a73329007..7bea184b7338 100644 --- a/Documentation/process/index.rst +++ b/Documentation/process/index.rst @@ -110,10 +110,3 @@ developers: kernel-docs deprecated - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex` -- cgit v1.2.3 From 78a00cac1e962aacfe67ffa0ce295e709e0e6c5b Mon Sep 17 00:00:00 2001 From: Rhys Tumelty Date: Wed, 28 Jan 2026 22:02:31 +0000 Subject: docs: fix 're-use' -> 'reuse' in documentation Signed-off-by: Rhys Tumelty Acked-by: Randy Dunlap Signed-off-by: Jonathan Corbet Message-ID: <20260128220233.179439-1-rhys@tumelty.co.uk> --- Documentation/process/adding-syscalls.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'Documentation/process') diff --git a/Documentation/process/adding-syscalls.rst b/Documentation/process/adding-syscalls.rst index e8892f03eadd..91fc88681b1e 100644 --- a/Documentation/process/adding-syscalls.rst +++ b/Documentation/process/adding-syscalls.rst @@ -117,7 +117,7 @@ then the flags argument should include a value that is equivalent to setting the timing window between ``xyzzy()`` and calling ``fcntl(fd, F_SETFD, FD_CLOEXEC)``, where an unexpected ``fork()`` and ``execve()`` in another thread could leak a descriptor to -the exec'ed program. (However, resist the temptation to re-use the actual value +the exec'ed program. (However, resist the temptation to reuse the actual value of the ``O_CLOEXEC`` constant, as it is architecture-specific and is part of a numbering space of ``O_*`` flags that is fairly full.) @@ -459,7 +459,7 @@ the compatibility wrapper:: ... 555 x32 xyzzy __x32_compat_sys_xyzzy -If no pointers are involved, then it is preferable to re-use the 64-bit system +If no pointers are involved, then it is preferable to reuse the 64-bit system call for the x32 ABI (and consequently the entry in arch/x86/entry/syscalls/syscall_64.tbl is unchanged). -- cgit v1.2.3 From 0a83293322fde69f1fb4722bd3c79c2d52eef436 Mon Sep 17 00:00:00 2001 From: Dmitry Antipov Date: Fri, 23 Jan 2026 10:15:23 +0300 Subject: doc: development-process: add notice on testing Add testing notice to "Before creating patches" section. Suggested-by: Andy Shevchenko Signed-off-by: Dmitry Antipov Acked-by: Randy Dunlap Acked-by: Andy Shevchenko Signed-off-by: Jonathan Corbet Message-ID: <20260123071523.1392729-1-dmantipov@yandex.ru> --- Documentation/process/5.Posting.rst | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) (limited to 'Documentation/process') diff --git a/Documentation/process/5.Posting.rst b/Documentation/process/5.Posting.rst index 9999bcbdccc9..07d7dbed13ec 100644 --- a/Documentation/process/5.Posting.rst +++ b/Documentation/process/5.Posting.rst @@ -40,7 +40,12 @@ sending patches to the development community. These include: - Test the code to the extent that you can. Make use of the kernel's debugging tools, ensure that the kernel will build with all reasonable combinations of configuration options, use cross-compilers to build for - different architectures, etc. + different architectures, etc. Add tests, likely using an existing + testing framework like KUnit, and include them as a separate member + of your series (see the next section for more about patch series). + Note that this may be mandatory when affecting some subsystems. For + example, library functions (resides under lib/) are extensively used + almost everywhere and expected to be tested appropriately. - Make sure your code is compliant with the kernel coding style guidelines. -- cgit v1.2.3