From 2fec7b33094c1257ddb07b2b8318cfccba235d58 Mon Sep 17 00:00:00 2001 From: Bart Van Assche Date: Mon, 7 Jan 2019 10:20:19 -0800 Subject: Documentation/CodingStyle: Use directory-local variables for emacs settings In emacs 23.1 support for directory-local variables was added (see also https://lists.gnu.org/archive/html/info-gnu-emacs/2009-07/msg00000.html). Simplify the settings in coding-style.rst by using that feature. Additionally, do not inherit any settings from emacs' linux coding style to minimize dependencies on the version of emacs that is being used. I have verified with several large and nontrivial kernel source files that the new settings format code according to what checkpatch expects. Signed-off-by: Bart Van Assche Cc: Matthew Wilcox Cc: Jani Nikula Cc: Alison Chaiken Cc: Joe Perches Cc: Federico Vaga Cc: Geyslan G. Bem Cc: Tiago Natel de Moura Signed-off-by: Jonathan Corbet --- Documentation/process/coding-style.rst | 57 ++++++++++++++++++++++------------ 1 file changed, 37 insertions(+), 20 deletions(-) (limited to 'Documentation/process') diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst index b78dd680c038..afa11024279a 100644 --- a/Documentation/process/coding-style.rst +++ b/Documentation/process/coding-style.rst @@ -595,26 +595,43 @@ values. To do the latter, you can stick the following in your .emacs file: (* (max steps 1) c-basic-offset))) - (add-hook 'c-mode-common-hook - (lambda () - ;; Add kernel style - (c-add-style - "linux-tabs-only" - '("linux" (c-offsets-alist - (arglist-cont-nonempty - c-lineup-gcc-asm-reg - c-lineup-arglist-tabs-only)))))) - - (add-hook 'c-mode-hook - (lambda () - (let ((filename (buffer-file-name))) - ;; Enable kernel mode for the appropriate files - (when (and filename - (string-match (expand-file-name "~/src/linux-trees") - filename)) - (setq indent-tabs-mode t) - (setq show-trailing-whitespace t) - (c-set-style "linux-tabs-only"))))) + (dir-locals-set-class-variables + 'linux-kernel + '((c-mode . ( + (c-basic-offset . 8) + (c-label-minimum-indentation . 0) + (c-offsets-alist . ( + (arglist-close . c-lineup-arglist-tabs-only) + (arglist-cont-nonempty . + (c-lineup-gcc-asm-reg c-lineup-arglist-tabs-only)) + (arglist-intro . +) + (brace-list-intro . +) + (c . c-lineup-C-comments) + (case-label . 0) + (comment-intro . c-lineup-comment) + (cpp-define-intro . +) + (cpp-macro . -1000) + (cpp-macro-cont . +) + (defun-block-intro . +) + (else-clause . 0) + (func-decl-cont . +) + (inclass . +) + (inher-cont . c-lineup-multi-inher) + (knr-argdecl-intro . 0) + (label . -1000) + (statement . 0) + (statement-block-intro . +) + (statement-case-intro . +) + (statement-cont . +) + (substatement . +) + )) + (indent-tabs-mode . t) + (show-trailing-whitespace . t) + )))) + + (dir-locals-set-directory-class + (expand-file-name "~/src/linux-trees") + 'linux-kernel) This will make emacs go better with the kernel coding style for C files below ``~/src/linux-trees``. -- cgit v1.2.3 From 7fbc258fea74d888b5ac6ba15c50ef2a05b5243b Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Sun, 13 Jan 2019 19:28:58 -0800 Subject: Documentation: fix coding-style.rst Sphinx warning Fix Sphinx warning in coding-style.rst: Documentation/process/coding-style.rst:446: WARNING: Inline interpreted text or phrase reference start-string without end-string. Signed-off-by: Randy Dunlap Signed-off-by: Jonathan Corbet --- 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 afa11024279a..4e611a01adc6 100644 --- a/Documentation/process/coding-style.rst +++ b/Documentation/process/coding-style.rst @@ -443,7 +443,7 @@ In function prototypes, include parameter names with their data types. Although this is not required by the C language, it is preferred in Linux because it is a simple way to add valuable information for the reader. -Do not use the `extern' keyword with function prototypes as this makes +Do not use the ``extern`` keyword with function prototypes as this makes lines longer and isn't strictly necessary. -- cgit v1.2.3 From 1d2375f048b7da90402c7a40fb3606b320c3f76f Mon Sep 17 00:00:00 2001 From: Federico Vaga Date: Fri, 18 Jan 2019 22:58:04 +0100 Subject: doc:process: remove note from 'stable api nonsense' The link referred by the note can't be retrieved: this patch just remove that old note. Signed-off-by: Federico Vaga Acked-by: Greg Kroah-Hartman Signed-off-by: Jonathan Corbet --- Documentation/process/stable-api-nonsense.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) (limited to 'Documentation/process') diff --git a/Documentation/process/stable-api-nonsense.rst b/Documentation/process/stable-api-nonsense.rst index 24f5aeecee91..57d95a49c096 100644 --- a/Documentation/process/stable-api-nonsense.rst +++ b/Documentation/process/stable-api-nonsense.rst @@ -171,8 +171,7 @@ is also a rough job. Simple, get your kernel driver into the main kernel tree (remember we are talking about GPL released drivers here, if your code doesn't fall -under this category, good luck, you are on your own here, you leech -.) If your +under this category, good luck, you are on your own here, you leech). If your driver is in the tree, and a kernel interface changes, it will be fixed up by the person who did the kernel change in the first place. This ensures that your driver is always buildable, and works over time, with -- cgit v1.2.3 From b04c11c988f4fcfba037ce6c356ea5ac9e23df63 Mon Sep 17 00:00:00 2001 From: Federico Vaga Date: Sun, 20 Jan 2019 12:16:29 +0100 Subject: doc:process: add missing internal link in stable-kernel-rules Keep consistent the document. In the document, option references are always linked, except for the one I fixed with this patch Signed-off-by: Federico Vaga Signed-off-by: Jonathan Corbet --- Documentation/process/stable-kernel-rules.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'Documentation/process') diff --git a/Documentation/process/stable-kernel-rules.rst b/Documentation/process/stable-kernel-rules.rst index 0de6f6145cc6..070e3f04d183 100644 --- a/Documentation/process/stable-kernel-rules.rst +++ b/Documentation/process/stable-kernel-rules.rst @@ -98,9 +98,9 @@ text, like this: commit upstream. -Additionally, some patches submitted via Option 1 may have additional patch -prerequisites which can be cherry-picked. This can be specified in the following -format in the sign-off area: +Additionally, some patches submitted via :ref:`option_1` may have additional +patch prerequisites which can be cherry-picked. This can be specified in the +following format in the sign-off area: .. code-block:: none -- cgit v1.2.3 From 7967656ffbfa493f5546c0f18bf8a28f702c4baa Mon Sep 17 00:00:00 2001 From: Jason Gunthorpe Date: Fri, 18 Jan 2019 15:50:47 -0700 Subject: coding-style: Clarify the expectations around bool There has been some confusion since checkpatch started warning about bool use in structures, and people have been avoiding using it. Many people feel there is still a legitimate place for bool in structures, so provide some guidance on bool usage derived from the entire thread that spawned the checkpatch warning. Link: https://lkml.kernel.org/r/CA+55aFwVZk1OfB9T2v014PTAKFhtVan_Zj2dOjnCy3x6E4UJfA@mail.gmail.com Signed-off-by: Joe Perches Acked-by: Joe Perches Reviewed-by: Bart Van Assche Acked-by: Jani Nikula Reviewed-by: Joey Pabalinas Signed-off-by: Jason Gunthorpe Signed-off-by: Jonathan Corbet --- Documentation/process/coding-style.rst | 38 ++++++++++++++++++++++++++++++---- 1 file changed, 34 insertions(+), 4 deletions(-) (limited to 'Documentation/process') diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst index 4e611a01adc6..8ea913e99fa1 100644 --- a/Documentation/process/coding-style.rst +++ b/Documentation/process/coding-style.rst @@ -938,7 +938,37 @@ result. Typical examples would be functions that return pointers; they use NULL or the ERR_PTR mechanism to report failure. -17) Don't re-invent the kernel macros +17) Using bool +-------------- + +The Linux kernel bool type is an alias for the C99 _Bool type. bool values can +only evaluate to 0 or 1, and implicit or explicit conversion to bool +automatically converts the value to true or false. When using bool types the +!! construction is not needed, which eliminates a class of bugs. + +When working with bool values the true and false definitions should be used +instead of 1 and 0. + +bool function return types and stack variables are always fine to use whenever +appropriate. Use of bool is encouraged to improve readability and is often a +better option than 'int' for storing boolean values. + +Do not use bool if cache line layout or size of the value matters, as its size +and alignment varies based on the compiled architecture. Structures that are +optimized for alignment and size should not use bool. + +If a structure has many true/false values, consider consolidating them into a +bitfield with 1 bit members, or using an appropriate fixed width type, such as +u8. + +Similarly for function arguments, many true/false values can be consolidated +into a single bitwise 'flags' argument and 'flags' can often be a more +readable alternative if the call-sites have naked true/false constants. + +Otherwise limited use of bool in structures and arguments can improve +readability. + +18) Don't re-invent the kernel macros ------------------------------------- The header file include/linux/kernel.h contains a number of macros that @@ -961,7 +991,7 @@ need them. Feel free to peruse that header file to see what else is already defined that you shouldn't reproduce in your code. -18) Editor modelines and other cruft +19) Editor modelines and other cruft ------------------------------------ Some editors can interpret configuration information embedded in source files, @@ -995,7 +1025,7 @@ own custom mode, or may have some other magic method for making indentation work correctly. -19) Inline assembly +20) Inline assembly ------------------- In architecture-specific code, you may need to use inline assembly to interface @@ -1027,7 +1057,7 @@ the next instruction in the assembly output: : /* outputs */ : /* inputs */ : /* clobbers */); -20) Conditional Compilation +21) Conditional Compilation --------------------------- Wherever possible, don't use preprocessor conditionals (#if, #ifdef) in .c -- cgit v1.2.3 From 19c1d46dfc7793b53b89c796475399656b9a794a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jonathan=20Neusch=C3=A4fer?= Date: Wed, 30 Jan 2019 18:25:15 +0100 Subject: doc: Change LXR references to elixir.bootlin.com MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Recently, Free Electrons was renamed to Bootlin[1]. Less recently, the Linux Cross Reference (LXR) at lxr.free-electrons.com was replaced by Elixir[2], and lxr.free-electrons.com redirected first to elixir.free-electrons.com and now to elixir.bootlin.com. [1]: https://bootlin.com/blog/free-electrons-becomes-bootlin/ [2]: https://github.com/free-electrons/elixir Signed-off-by: Jonathan Neuschäfer Reviewed-by: Martin Kepplinger Acked-by: Federico Vaga Signed-off-by: Jonathan Corbet --- Documentation/process/howto.rst | 2 +- Documentation/process/kernel-docs.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) (limited to 'Documentation/process') diff --git a/Documentation/process/howto.rst b/Documentation/process/howto.rst index 58b2f46c4f98..bdd2eda81a1c 100644 --- a/Documentation/process/howto.rst +++ b/Documentation/process/howto.rst @@ -225,7 +225,7 @@ Cross-Reference project, which is able to present source code in a self-referential, indexed webpage format. An excellent up-to-date repository of the kernel code may be found at: - http://lxr.free-electrons.com/ + https://elixir.bootlin.com/ The development process diff --git a/Documentation/process/kernel-docs.rst b/Documentation/process/kernel-docs.rst index 3fb28de556e4..ab12dddc773e 100644 --- a/Documentation/process/kernel-docs.rst +++ b/Documentation/process/kernel-docs.rst @@ -565,7 +565,7 @@ Miscellaneous * Name: **Cross-Referencing Linux** - :URL: http://lxr.free-electrons.com/ + :URL: https://elixir.bootlin.com/ :Keywords: Browsing source code. :Description: Another web-based Linux kernel source code browser. Lots of cross references to variables and functions. You can see -- cgit v1.2.3 From a41e8f25fa8f8f67360d88eb0eebbabe95a64bdf Mon Sep 17 00:00:00 2001 From: Greg Kroah-Hartman Date: Tue, 22 Jan 2019 19:46:32 +0100 Subject: stable-kernel-rules.rst: add link to networking patch queue The networking maintainer keeps a public list of the patches being queued up for the next round of stable releases. Be sure to check there before asking for a patch to be applied so that you do not waste people's time. Signed-off-by: Greg Kroah-Hartman Acked-by: David S. Miller Signed-off-by: Jonathan Corbet --- Documentation/process/stable-kernel-rules.rst | 3 +++ 1 file changed, 3 insertions(+) (limited to 'Documentation/process') diff --git a/Documentation/process/stable-kernel-rules.rst b/Documentation/process/stable-kernel-rules.rst index 070e3f04d183..06f743b612c4 100644 --- a/Documentation/process/stable-kernel-rules.rst +++ b/Documentation/process/stable-kernel-rules.rst @@ -38,6 +38,9 @@ Procedure for submitting patches to the -stable tree - If the patch covers files in net/ or drivers/net please follow netdev stable submission guidelines as described in :ref:`Documentation/networking/netdev-FAQ.rst ` + after first checking the stable networking queue at + https://patchwork.ozlabs.org/bundle/davem/stable/?series=&submitter=&state=*&q=&archive= + to ensure the requested patch is not already queued up. - Security patches should not be handled (solely) by the -stable review process but should follow the procedures in :ref:`Documentation/admin-guide/security-bugs.rst `. -- cgit v1.2.3 From 8f7e6d134bda563c9b3abac14de11e89eb4c86d7 Mon Sep 17 00:00:00 2001 From: Adam Borowski Date: Tue, 22 Jan 2019 10:34:08 +0100 Subject: doc: process: GPL -> GPL-compatible Drivers under MIT, BSD-17-clause, or uncle-Bob's-newest-take-on-PD are all fine, not just GPL. Signed-off-by: Adam Borowski [jc: fixed conflict and refilled paragraph] Reviewed-by: Greg Kroah-Hartman Signed-off-by: Jonathan Corbet --- Documentation/process/stable-api-nonsense.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) (limited to 'Documentation/process') diff --git a/Documentation/process/stable-api-nonsense.rst b/Documentation/process/stable-api-nonsense.rst index 57d95a49c096..a9625ab1fdc2 100644 --- a/Documentation/process/stable-api-nonsense.rst +++ b/Documentation/process/stable-api-nonsense.rst @@ -169,13 +169,13 @@ driver for every different kernel version for every distribution is a nightmare, and trying to keep up with an ever changing kernel interface is also a rough job. -Simple, get your kernel driver into the main kernel tree (remember we -are talking about GPL released drivers here, if your code doesn't fall -under this category, good luck, you are on your own here, you leech). If your -driver is in the tree, and a kernel interface changes, it will be fixed -up by the person who did the kernel change in the first place. This -ensures that your driver is always buildable, and works over time, with -very little effort on your part. +Simple, get your kernel driver into the main kernel tree (remember we are +talking about drivers released under a GPL-compatible license here, if your +code doesn't fall under this category, good luck, you are on your own here, +you leech). If your driver is in the tree, and a kernel interface changes, +it will be fixed up by the person who did the kernel change in the first +place. This ensures that your driver is always buildable, and works over +time, with very little effort on your part. The very good side effects of having your driver in the main kernel tree are: -- cgit v1.2.3 From bf7fbeeae6db644ef5995085de2bc5c6121f8c8d Mon Sep 17 00:00:00 2001 From: Thomas Gleixner Date: Fri, 8 Feb 2019 17:02:56 +0100 Subject: module: Cure the MODULE_LICENSE "GPL" vs. "GPL v2" bogosity The original MODULE_LICENSE string for kernel modules licensed under the GPL v2 (only / or later) was simply "GPL", which was - and still is - completely sufficient for the purpose of module loading and checking whether the module is free software or proprietary. In January 2003 this was changed with commit 3344ea3ad4b7 ("[PATCH] MODULE_LICENSE and EXPORT_SYMBOL_GPL support"). This commit can be found in the history git repository which holds the 1:1 import of Linus' bitkeeper repository: https://git.kernel.org/pub/scm/linux/kernel/git/tglx/history.git/commit/?id=3344ea3ad4b7c302c846a680dbaeedf96ed45c02 The main intention of the patch was to refuse linking proprietary modules against symbols exported with EXPORT_SYMBOL_GPL() at module load time. As a completely undocumented side effect it also introduced the distinction between "GPL" and "GPL v2" MODULE_LICENSE() strings: * "GPL" [GNU Public License v2 or later] * "GPL v2" [GNU Public License v2] * "GPL and additional rights" [GNU Public License v2 rights and more] * "Dual BSD/GPL" [GNU Public License v2 * or BSD license choice] * "Dual MPL/GPL" [GNU Public License v2 * or Mozilla license choice] This distinction was and still is wrong in several aspects: 1) It broke all modules which were using the "GPL" string in the MODULE_LICENSE() already and were licensed under GPL v2 only. A quick license scan over the tree at that time shows that at least 480 out of 1484 modules have been affected by this change back then. The number is probably way higher as this was just a quick check for clearly identifiable license information. There was exactly ONE instance of a "GPL v2" module license string in the kernel back then - drivers/net/tulip/xircom_tulip_cb.c which otherwise had no license information at all. There is no indication that the change above is any way related to this driver. The change happend with the 2.4.11 release which was on Oct. 9 2001 - so quite some time before the above commit. Unfortunately there is no trace on the intertubes to any discussion of this. 2) The dual licensed strings became ill defined as well because following the "GPL" vs. "GPL v2" distinction all dual licensed (or additional rights) MODULE_LICENSE strings would either require those dual licensed modules to be licensed under GPL v2 or later or just be unspecified for the dual licensing case. Neither choice is coherent with the GPL distinction. Due to the lack of a proper changelog and no real discussion on the patch submission other than a few implementation details, it's completely unclear why this distinction was introduced at all. Other than the comment in the module header file exists no documentation for this at all. From a license compliance and license scanning POV this distinction is a total nightmare. As of 5.0-rc2 2873 out of 9200 instances of MODULE_LICENSE() strings are conflicting with the actual license in the source code (either SPDX or license boilerplate/reference). A comparison between the scan of the history tree and a scan of current Linus tree shows to the extent that the git rename detection over Linus tree grafted with the history tree is halfways complete that almost none of the files which got broken in 2003 have been cleaned up vs. the MODULE_LICENSE string. So subtracting those 480 known instances from the conflicting 2800 of today more than 25% of the module authors got it wrong and it's a high propability that a large portion of the rest just got it right by chance. There is no value for the module loader to convey the detailed license information as the only decision to be made is whether the module is free software or not. The "and additional rights", "BSD" and "MPL" strings are not conclusive license information either. So there is no point in trying to make the GPL part conclusive and exact. As shown above it's already non conclusive for dual licensing and incoherent with a large portion of the module source. As an unintended side effect this distinction causes a major headache for license compliance, license scanners and the ongoing effort to clean up the license mess of the kernel. Therefore remove the well meant, but ill defined, distinction between "GPL" and "GPL v2" and document that: - "GPL" and "GPL v2" both express that the module is licensed under GPLv2 (without a distinction of 'only' and 'or later') and is therefore kernel license compliant. - None of the MODULE_LICENSE strings can be used for expressing or determining the exact license - Their sole purpose is to decide whether the module is free software or not. Add a MODULE_LICENSE subsection to the license rule documentation as well. Signed-off-by: Thomas Gleixner Reviewed-by: Greg Kroah-Hartman Acked-by: Philippe Ombredanne Acked-by: Joe Perches [jc: Did s/merily/merely/ ] Acked-by: Jessica Yu Signed-off-by: Jonathan Corbet --- Documentation/process/license-rules.rst | 62 +++++++++++++++++++++++++++++++++ 1 file changed, 62 insertions(+) (limited to 'Documentation/process') diff --git a/Documentation/process/license-rules.rst b/Documentation/process/license-rules.rst index 2bb8c0fc2238..43b6a1ee0193 100644 --- a/Documentation/process/license-rules.rst +++ b/Documentation/process/license-rules.rst @@ -372,3 +372,65 @@ in the LICENSE subdirectories. This is required to allow tool verification (e.g. checkpatch.pl) and to have the licenses ready to read and extract right from the source, which is recommended by various FOSS organizations, e.g. the `FSFE REUSE initiative `_. + +_`MODULE_LICENSE` +----------------- + + Loadable kernel modules also require a MODULE_LICENSE() tag. This tag is + neither a replacement for proper source code license information + (SPDX-License-Identifier) nor in any way relevant for expressing or + determining the exact license under which the source code of the module + is provided. + + The sole purpose of this tag is to provide sufficient information + whether the module is free software or proprietary for the kernel + module loader and for user space tools. + + The valid license strings for MODULE_LICENSE() are: + + ============================= ============================================= + "GPL" Module is licensed under GPL version 2. This + does not express any distinction between + GPL-2.0-only or GPL-2.0-or-later. The exact + license information can only be determined + via the license information in the + corresponding source files. + + "GPL v2" Same as "GPL". It exists for historic + reasons. + + "GPL and additional rights" Historical variant of expressing that the + module source is dual licensed under a + GPL v2 variant and MIT license. Please do + not use in new code. + + "Dual MIT/GPL" The correct way of expressing that the + module is dual licensed under a GPL v2 + variant or MIT license choice. + + "Dual BSD/GPL" The module is dual licensed under a GPL v2 + variant or BSD license choice. The exact + variant of the BSD license can only be + determined via the license information + in the corresponding source files. + + "Dual MPL/GPL" The module is dual licensed under a GPL v2 + variant or Mozilla Public License (MPL) + choice. The exact variant of the MPL + license can only be determined via the + license information in the corresponding + source files. + + "Proprietary" The module is under a proprietary license. + This string is solely for proprietary third + party modules and cannot be used for modules + which have their source code in the kernel + tree. Modules tagged that way are tainting + the kernel with the 'P' flag when loaded and + the kernel module loader refuses to link such + modules against symbols which are exported + with EXPORT_SYMBOL_GPL(). + ============================= ============================================= + + + -- cgit v1.2.3 From 2c71d305caf9cd5076873c6a57d22ab8cb7c906c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jonathan=20Neusch=C3=A4fer?= Date: Sun, 10 Feb 2019 18:12:59 +0100 Subject: docs: process: Remove outdated info about -git patches MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit As can be seen by clicking around the timeline on web.archive.org[1], there were no -git patches/tarballs on kernel.org since release 3.1. [1]: https://web.archive.org/web/20111103073843/http://www.kernel.org/ Signed-off-by: Jonathan Neuschäfer Signed-off-by: Jonathan Corbet --- Documentation/process/howto.rst | 9 --------- 1 file changed, 9 deletions(-) (limited to 'Documentation/process') diff --git a/Documentation/process/howto.rst b/Documentation/process/howto.rst index bdd2eda81a1c..64deab5cfb3b 100644 --- a/Documentation/process/howto.rst +++ b/Documentation/process/howto.rst @@ -302,15 +302,6 @@ The file :ref:`Documentation/process/stable-kernel-rules.rst Date: Thu, 21 Feb 2019 21:30:00 +0100 Subject: doc: process: complete removal of info about -git patches The following patch forgot to remove a reference to the -git patches commit 2c71d305caf9 ("docs: process: Remove outdated info about -git patches") This patch complete the removal and update all translations Signed-off-by: Federico Vaga Acked-by: SeongJae Park Signed-off-by: Jonathan Corbet --- Documentation/process/howto.rst | 1 - 1 file changed, 1 deletion(-) (limited to 'Documentation/process') diff --git a/Documentation/process/howto.rst b/Documentation/process/howto.rst index 64deab5cfb3b..f16242bfb962 100644 --- a/Documentation/process/howto.rst +++ b/Documentation/process/howto.rst @@ -237,7 +237,6 @@ branches. These different branches are: - main 4.x kernel tree - 4.x.y -stable kernel tree - - 4.x -git kernel patches - subsystem specific kernel trees and patches - the 4.x -next kernel tree for integration tests -- cgit v1.2.3 From 61ab9fecaf4fb829d21bbc3ec6679b1505fd61e8 Mon Sep 17 00:00:00 2001 From: Federico Vaga Date: Wed, 20 Feb 2019 23:46:09 +0100 Subject: doc: fix typos in license-rules.rst The patches fixes some typos in process/license-rules.rst Signed-off-by: Federico Vaga Signed-off-by: Jonathan Corbet --- Documentation/process/license-rules.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'Documentation/process') diff --git a/Documentation/process/license-rules.rst b/Documentation/process/license-rules.rst index 43b6a1ee0193..6b09033a8e9e 100644 --- a/Documentation/process/license-rules.rst +++ b/Documentation/process/license-rules.rst @@ -62,7 +62,7 @@ License identifier syntax The SPDX license identifier in kernel files shall be added at the first possible line in a file which can contain a comment. For the majority - or files this is the first line, except for scripts which require the + of files this is the first line, except for scripts which require the '#!PATH_TO_INTERPRETER' in the first line. For those scripts the SPDX identifier goes into the second line. @@ -368,7 +368,7 @@ kernel, can be broken down into: All SPDX license identifiers and exceptions must have a corresponding file -in the LICENSE subdirectories. This is required to allow tool +in the LICENSES subdirectories. This is required to allow tool verification (e.g. checkpatch.pl) and to have the licenses ready to read and extract right from the source, which is recommended by various FOSS organizations, e.g. the `FSFE REUSE initiative `_. -- cgit v1.2.3 From 19c3fe285cbaa5aa36d60638fc5c37706f2a1c3e Mon Sep 17 00:00:00 2001 From: Sean Christopherson Date: Tue, 19 Feb 2019 07:27:15 -0800 Subject: docs: Explicitly state that the 'Fixes:' tag shouldn't split lines ...and use a commit with an obnoxiously long summary in the example to make it abundantly clear that keeping the tag on a single line takes priority over wrapping at 75 columns. Without the explicit exemption, one might assume splitting the tag is acceptable, even encouraged, e.g. due to being conditioned by checkpatch's line length warning. Per Stephen's scripts[1] and implied by commit bf4daf12a9fb ("checkpatch: avoid some commit message long line warnings"), splitting the 'Fixes:' tag across multiple lines is a no-no, presumably because parsing multi- line tags is unnecessarily painful. [1] https://lkml.kernel.org/r/20190216183433.71b7cfa7@canb.auug.org.au Cc: Stephen Rothwell Signed-off-by: Sean Christopherson Signed-off-by: Jonathan Corbet --- Documentation/process/submitting-patches.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) (limited to 'Documentation/process') diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst index 30dc00a364e8..be7d1829c3af 100644 --- a/Documentation/process/submitting-patches.rst +++ b/Documentation/process/submitting-patches.rst @@ -182,9 +182,11 @@ change five years from now. If your patch fixes a bug in a specific commit, e.g. you found an issue using ``git bisect``, please use the 'Fixes:' tag with the first 12 characters of -the SHA-1 ID, and the one line summary. For example:: +the SHA-1 ID, and the one line summary. Do not split the tag across multiple +lines, tags are exempt from the "wrap at 75 columns" rule in order to simplify +parsing scripts. For example:: - Fixes: e21d2170f366 ("video: remove unnecessary platform_set_drvdata()") + Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed") The following ``git config`` settings can be used to add a pretty format for outputting the above style in the ``git log`` or ``git show`` commands:: -- cgit v1.2.3 From d2b008f134b787c067b987c61f949b7768bb8b27 Mon Sep 17 00:00:00 2001 From: Zenghui Yu Date: Wed, 27 Feb 2019 02:22:22 +0800 Subject: Documentation/process/howto: Update for 4.x -> 5.x versioning As linux-5.0 is coming up soon, the howto.rst document can be updated for the new kernel version. Instead of changing all 4.x references to 5.x, this time we git rid of all explicit version numbers and rework some kernel trees' name to keep the docs current and real. Signed-off-by: Zenghui Yu Signed-off-by: Jonathan Corbet --- Documentation/process/howto.rst | 47 +++++++++++++++++++---------------------- 1 file changed, 22 insertions(+), 25 deletions(-) (limited to 'Documentation/process') diff --git a/Documentation/process/howto.rst b/Documentation/process/howto.rst index f16242bfb962..ad2b6c852b95 100644 --- a/Documentation/process/howto.rst +++ b/Documentation/process/howto.rst @@ -235,22 +235,21 @@ Linux kernel development process currently consists of a few different main kernel "branches" and lots of different subsystem-specific kernel branches. These different branches are: - - main 4.x kernel tree - - 4.x.y -stable kernel tree - - subsystem specific kernel trees and patches - - the 4.x -next kernel tree for integration tests + - Linus's mainline tree + - Various stable trees with multiple major numbers + - Subsystem-specific trees + - linux-next integration testing tree -4.x kernel tree -~~~~~~~~~~~~~~~ +Mainline tree +~~~~~~~~~~~~~ -4.x kernels are maintained by Linus Torvalds, and can be found on -https://kernel.org in the pub/linux/kernel/v4.x/ directory. Its development -process is as follows: +Mainline tree are maintained by Linus Torvalds, and can be found at +https://kernel.org or in the repo. Its development process is as follows: - As soon as a new kernel is released a two weeks window is open, during this period of time maintainers can submit big diffs to Linus, usually the patches that have already been included in the - -next kernel for a few weeks. The preferred way to submit big changes + linux-next for a few weeks. The preferred way to submit big changes is using git (the kernel's source management tool, more information can be found at https://git-scm.com/) but plain patches are also just fine. @@ -277,21 +276,19 @@ mailing list about kernel releases: released according to perceived bug status, not according to a preconceived timeline."* -4.x.y -stable kernel tree -~~~~~~~~~~~~~~~~~~~~~~~~~ +Various stable trees with multiple major numbers +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Kernels with 3-part versions are -stable kernels. They contain relatively small and critical fixes for security problems or significant -regressions discovered in a given 4.x kernel. +regressions discovered in a given major mainline release, with the first +2-part of version number are the same correspondingly. This is the recommended branch for users who want the most recent stable kernel and are not interested in helping test development/experimental versions. -If no 4.x.y kernel is available, then the highest numbered 4.x -kernel is the current stable kernel. - -4.x.y are maintained by the "stable" team , and +Stable trees are maintained by the "stable" team , and are released as needs dictate. The normal release period is approximately two weeks, but it can be longer if there are no pressing problems. A security-related problem, instead, can cause a release to happen almost @@ -301,8 +298,8 @@ The file :ref:`Documentation/process/stable-kernel-rules.rst