diff options
Diffstat (limited to 'Documentation/process')
28 files changed, 1006 insertions, 367 deletions
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..77f3f80e7cd7 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 @@ -291,7 +291,7 @@ Use of the MMOTM tree is likely to be a frustrating experience, though; there is a definite chance that it will not even compile. The primary tree for next-cycle patch merging is linux-next, maintained by -Stephen Rothwell. The linux-next tree is, by design, a snapshot of what +Mark Brown. The linux-next tree is, by design, a snapshot of what the mainline is expected to look like after the next merge window closes. Linux-next trees are announced on the linux-kernel and linux-next mailing lists when they are assembled; they can be downloaded from: 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/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. 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. diff --git a/Documentation/process/adding-syscalls.rst b/Documentation/process/adding-syscalls.rst index fc0b0bbcd34d..91fc88681b1e 100644 --- a/Documentation/process/adding-syscalls.rst +++ b/Documentation/process/adding-syscalls.rst @@ -111,13 +111,13 @@ 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 ``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.) @@ -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 @@ -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). diff --git a/Documentation/process/backporting.rst b/Documentation/process/backporting.rst index c42779fbcd33..0de9eacd46a7 100644 --- a/Documentation/process/backporting.rst +++ b/Documentation/process/backporting.rst @@ -432,7 +432,7 @@ The same goes for added ``return``, ``break``, and ``continue`` statements. Error handling is typically located at the bottom of the function, so it -may not be part of the conflict even though could have been changed by +may not be part of the conflict even though it could have been changed by other patches. A good way to ensure that you review the error paths is to always use diff --git a/Documentation/process/changes.rst b/Documentation/process/changes.rst index 62951cdb13ad..9a99037270ff 100644 --- a/Documentation/process/changes.rst +++ b/Documentation/process/changes.rst @@ -19,50 +19,52 @@ Current Minimal Requirements Upgrade to at **least** these software revisions before thinking you've encountered a bug! If you're unsure what version you're currently -running, the suggested command should tell you. +running, the suggested command should tell you. For a list of the programs +on your system including their version execute ./scripts/ver_linux Again, keep in mind that this list assumes you are already functionally running a Linux kernel. Also, not all tools are necessary on all systems; obviously, if you don't have any PC Card hardware, for example, -you probably needn't concern yourself with pcmciautils. +you probably do not need to concern yourself with pcmciautils. ====================== =============== ======================================== Program Minimal version Command to check the version ====================== =============== ======================================== -GNU C 8.1 gcc --version -Clang/LLVM (optional) 15.0.0 clang --version -Rust (optional) 1.78.0 rustc --version -bindgen (optional) 0.65.1 bindgen --version -GNU make 4.0 make --version bash 4.2 bash --version +bc 1.06.95 bc --version +bindgen (optional) 0.71.1 bindgen --version binutils 2.30 ld -v -flex 2.5.35 flex --version bison 2.0 bison --version -pahole 1.16 pahole --version -util-linux 2.10o mount --version -kmod 13 depmod -V +btrfs-progs 0.18 btrfs --version +Clang/LLVM (optional) 15.0.0 clang --version e2fsprogs 1.41.4 e2fsck -V +flex 2.5.35 flex --version +gdb 7.2 gdb --version +GNU awk (optional) 5.1.0 gawk --version +GNU C 8.1 gcc --version +GNU make 4.0 make --version +GNU tar 1.28 tar --version +GRUB 0.93 grub --version || grub-install --version +gtags (optional) 6.6.5 gtags --version +iptables 1.4.2 iptables -V jfsutils 1.1.3 fsck.jfs -V -xfsprogs 2.6.0 xfs_db -V -squashfs-tools 4.0 mksquashfs -version -btrfs-progs 0.18 btrfs --version +kmod 13 kmod -V +mcelog 0.6 mcelog --version +mkimage (optional) 2017.01 mkimage --version +nfs-utils 1.0.5 showmount --version +openssl & libcrypto 1.0.0 openssl version +pahole 1.22 pahole --version pcmciautils 004 pccardctl -V -quota-tools 3.09 quota -V PPP 2.4.0 pppd --version -nfs-utils 1.0.5 showmount --version procps 3.2.0 ps --version -udev 081 udevd --version -grub 0.93 grub --version || grub-install --version -mcelog 0.6 mcelog --version -iptables 1.4.2 iptables -V -openssl & libcrypto 1.0.0 openssl version -bc 1.06.95 bc --version -Sphinx\ [#f1]_ 3.4.3 sphinx-build --version -GNU tar 1.28 tar --version -gtags (optional) 6.6.5 gtags --version -mkimage (optional) 2017.01 mkimage --version Python 3.9.x python3 --version -GNU AWK (optional) 5.1.0 gawk --version +quota-tools 3.09 quota -V +Rust (optional) 1.85.0 rustc --version +Sphinx\ [#f1]_ 3.4.3 sphinx-build --version +squashfs-tools 4.0 mksquashfs -version +udev 081 udevadm --version +util-linux 2.10o mount --version +xfsprogs 2.6.0 xfs_db -V ====================== =============== ======================================== .. [#f1] Sphinx is needed only to build the Kernel documentation @@ -143,7 +145,7 @@ pahole Since Linux 5.2, if CONFIG_DEBUG_INFO_BTF is selected, the build system generates BTF (BPF Type Format) from DWARF in vmlinux, a bit later from kernel -modules as well. This requires pahole v1.16 or later. +modules as well. This requires pahole v1.22 or later. It is found in the 'dwarves' or 'pahole' distro packages or from https://fedorapeople.org/~acme/dwarves/. @@ -218,7 +220,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. @@ -391,7 +393,7 @@ Kernel documentation Sphinx ------ -Please see :ref:`sphinx_install` in :ref:`Documentation/doc-guide/sphinx.rst <sphinxdoc>` +Please see :ref:`sphinx_install` in Documentation/doc-guide/sphinx.rst for details about Sphinx requirements. rustdoc 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/coding-style.rst b/Documentation/process/coding-style.rst index 2969ca378dbb..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/ <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. @@ -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. diff --git a/Documentation/process/conclave.rst b/Documentation/process/conclave.rst new file mode 100644 index 000000000000..6a1234f54612 --- /dev/null +++ b/Documentation/process/conclave.rst @@ -0,0 +1,41 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Linux kernel project continuity +=============================== + +The Linux kernel development project is widely distributed, with over +100 maintainers each working to keep changes moving through their own +repositories. The final step, though, is a centralized one where changes +are pulled into the mainline repository. That is normally done by Linus +Torvalds but, as was demonstrated by the 4.19 release in 2018, there are +others who can do that work when the need arises. + +Should the maintainers of that repository become unwilling or unable to +do that work going forward (including facilitating a transition), the +project will need to find one or more replacements without delay. The +process by which that will be done is listed below. $ORGANIZER is the +last Maintainer Summit organizer or the current Linux Foundation (LF) +Technical Advisory Board (TAB) Chair as a backup. + +- Within 72 hours, $ORGANIZER will open a discussion with the invitees + of the most recently concluded Maintainers Summit. A meeting of those + invitees and the TAB, either online or in-person, will be set as soon + as possible in a way that maximizes the number of people who can + participate. + +- If there has been no Maintainers Summit in the last 15 months, the set of + invitees for this meeting will be determined by the TAB. + +- The invitees to this meeting may bring in other maintainers as needed. + +- This meeting, chaired by $ORGANIZER, will consider options for the + ongoing management of the top-level kernel repository consistent with + the expectation that it maximizes the long term health of the project + and its community. + +- Within two weeks, a representative of this group will communicate to the + broader community, using the ksummit@lists.linux.dev mailing list, what + the next steps will be. + +The Linux Foundation, as guided by the TAB, will take the steps +necessary to support and implement this plan. diff --git a/Documentation/process/debugging/gdb-kernel-debugging.rst b/Documentation/process/debugging/gdb-kernel-debugging.rst index 9475c759c722..53e225760a4d 100644 --- a/Documentation/process/debugging/gdb-kernel-debugging.rst +++ b/Documentation/process/debugging/gdb-kernel-debugging.rst @@ -173,3 +173,12 @@ this is just a snapshot of the initial version:: Detailed help can be obtained via "help <command-name>" for commands and "help function <function-name>" for convenience functions. + +Debugging GDB scripts +--------------------- + +GDB does not enable a full Python backtrace which can make debugging GDB +scripts more difficult than necessary. The following will allow for printing a +full backtrace of the python environment:: + + (gdb) set python print-stack full 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/debugging/kgdb.rst b/Documentation/process/debugging/kgdb.rst index b29b0aac2717..dd6a103073fa 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 ========= @@ -889,34 +896,6 @@ in the virtual console layer. On resuming kernel execution, the kernel debugger calls kgdboc_post_exp_handler() which in turn calls con_debug_leave(). -Any video driver that wants to be compatible with the kernel debugger -and the atomic kms callbacks must implement the ``mode_set_base_atomic``, -``fb_debug_enter`` and ``fb_debug_leave operations``. For the -``fb_debug_enter`` and ``fb_debug_leave`` the option exists to use the -generic drm fb helper functions or implement something custom for the -hardware. The following example shows the initialization of the -.mode_set_base_atomic operation in -drivers/gpu/drm/i915/intel_display.c:: - - - static const struct drm_crtc_helper_funcs intel_helper_funcs = { - [...] - .mode_set_base_atomic = intel_pipe_set_base_atomic, - [...] - }; - - -Here is an example of how the i915 driver initializes the -fb_debug_enter and fb_debug_leave functions to use the generic drm -helpers in ``drivers/gpu/drm/i915/intel_fb.c``:: - - - static struct fb_ops intelfb_ops = { - [...] - .fb_debug_enter = drm_fb_helper_debug_enter, - .fb_debug_leave = drm_fb_helper_debug_leave, - [...] - }; Credits diff --git a/Documentation/process/deprecated.rst b/Documentation/process/deprecated.rst index 1f7f3e6c9cda..fed56864d036 100644 --- a/Documentation/process/deprecated.rst +++ b/Documentation/process/deprecated.rst @@ -372,3 +372,34 @@ The helper must be used:: DECLARE_FLEX_ARRAY(struct type2, two); }; }; + +Open-coded kmalloc assignments for struct objects +------------------------------------------------- +Performing open-coded kmalloc()-family allocation assignments prevents +the kernel (and compiler) from being able to examine the type of the +variable being assigned, which limits any related introspection that +may help with alignment, wrap-around, or additional hardening. The +kmalloc_obj()-family of macros provide this introspection, which can be +used for the common code patterns for single, array, and flexible object +allocations. For example, these open coded assignments:: + + ptr = kmalloc(sizeof(*ptr), gfp); + ptr = kzalloc(sizeof(*ptr), gfp); + ptr = kmalloc_array(count, sizeof(*ptr), gfp); + ptr = kcalloc(count, sizeof(*ptr), gfp); + ptr = kmalloc(struct_size(ptr, flex_member, count), gfp); + ptr = kmalloc(sizeof(struct foo, gfp); + +become, respectively:: + + ptr = kmalloc_obj(*ptr, gfp); + ptr = kzalloc_obj(*ptr, gfp); + ptr = kmalloc_objs(*ptr, count, gfp); + ptr = kzalloc_objs(*ptr, count, gfp); + ptr = kmalloc_flex(*ptr, flex_member, count, gfp); + __auto_type ptr = kmalloc_obj(struct foo, gfp); + +If `ptr->flex_member` is annotated with __counted_by(), the allocation +will automatically fail if `count` is larger than the maximum +representable value that can be stored in the counter member associated +with `flex_member`. 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`! 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 |