diff options
Diffstat (limited to 'Documentation/process')
| -rw-r--r-- | Documentation/process/botching-up-ioctls.rst | 2 | ||||
| -rw-r--r-- | Documentation/process/changes.rst | 20 | ||||
| -rw-r--r-- | Documentation/process/deprecated.rst | 2 | ||||
| -rw-r--r-- | Documentation/process/kernel-docs.rst | 11 | ||||
| -rw-r--r-- | Documentation/process/maintainer-handbooks.rst | 1 | ||||
| -rw-r--r-- | Documentation/process/maintainer-netdev.rst | 6 | ||||
| -rw-r--r-- | Documentation/process/maintainer-soc-clean-dts.rst | 25 | ||||
| -rw-r--r-- | Documentation/process/maintainer-soc.rst | 4 | ||||
| -rw-r--r-- | Documentation/process/researcher-guidelines.rst | 27 | ||||
| -rw-r--r-- | Documentation/process/stable-kernel-rules.rst | 195 |
10 files changed, 194 insertions, 99 deletions
diff --git a/Documentation/process/botching-up-ioctls.rst b/Documentation/process/botching-up-ioctls.rst index 9739b88463a5..a05e8401de1c 100644 --- a/Documentation/process/botching-up-ioctls.rst +++ b/Documentation/process/botching-up-ioctls.rst @@ -208,7 +208,7 @@ Not every problem needs a new ioctl: it's much quicker to push a driver-private interface than engaging in lengthy discussions for a more generic solution. And occasionally doing a private interface to spearhead a new concept is what's required. But in the - end, once the generic interface comes around you'll end up maintainer two + end, once the generic interface comes around you'll end up maintaining two interfaces. Indefinitely. * Consider other interfaces than ioctls. A sysfs attribute is much better for diff --git a/Documentation/process/changes.rst b/Documentation/process/changes.rst index 5561dae94f85..b48da698d6f2 100644 --- a/Documentation/process/changes.rst +++ b/Documentation/process/changes.rst @@ -31,8 +31,8 @@ you probably needn't concern yourself with pcmciautils. ====================== =============== ======================================== GNU C 5.1 gcc --version Clang/LLVM (optional) 11.0.0 clang --version -Rust (optional) 1.68.2 rustc --version -bindgen (optional) 0.56.0 bindgen --version +Rust (optional) 1.71.1 rustc --version +bindgen (optional) 0.65.1 bindgen --version GNU make 3.82 make --version bash 4.2 bash --version binutils 2.25 ld -v @@ -482,7 +482,7 @@ E2fsprogs JFSutils -------- -- <http://jfs.sourceforge.net/> +- <https://jfs.sourceforge.net/> Reiserfsprogs ------------- @@ -503,7 +503,7 @@ Pcmciautils Quota-tools ----------- -- <http://sourceforge.net/projects/linuxquota/> +- <https://sourceforge.net/projects/linuxquota/> Intel P6 microcode @@ -524,7 +524,7 @@ FUSE mcelog ------ -- <http://www.mcelog.org/> +- <https://www.mcelog.org/> cpio ---- @@ -544,7 +544,8 @@ PPP NFS-utils --------- -- <http://sourceforge.net/project/showfiles.php?group_id=14> +- <https://sourceforge.net/project/showfiles.php?group_id=14> +- <https://nfs.sourceforge.net/> Iptables -------- @@ -559,12 +560,7 @@ Ip-route2 OProfile -------- -- <http://oprofile.sf.net/download/> - -NFS-Utils ---------- - -- <http://nfs.sourceforge.net/> +- <https://oprofile.sf.net/download/> Kernel documentation ******************** diff --git a/Documentation/process/deprecated.rst b/Documentation/process/deprecated.rst index f91b8441f2ef..1f7f3e6c9cda 100644 --- a/Documentation/process/deprecated.rst +++ b/Documentation/process/deprecated.rst @@ -77,7 +77,7 @@ kzalloc() can be replaced with kcalloc(). If no 2-factor form is available, the saturate-on-overflow helpers should be used:: - bar = vmalloc(array_size(count, size)); + bar = dma_alloc_coherent(dev, array_size(count, size), &dma, GFP_KERNEL); Another common case to avoid is calculating the size of a structure with a trailing array of others structures, as in:: diff --git a/Documentation/process/kernel-docs.rst b/Documentation/process/kernel-docs.rst index 46f927aae6eb..8660493b91d0 100644 --- a/Documentation/process/kernel-docs.rst +++ b/Documentation/process/kernel-docs.rst @@ -29,7 +29,7 @@ All documents are cataloged with the following fields: the document's The documents on each section of this document are ordered by its published date, from the newest to the oldest. The maintainer(s) should - periodically retire resources as they become obsolte or outdated; with + periodically retire resources as they become obsolete or outdated; with the exception of foundational books. Docs at the Linux Kernel tree @@ -118,6 +118,15 @@ Published books :ISBN: 978-0672329463 :Notes: Foundational book + * Title: **Practical Linux System Administration: A Guide to Installation, Configuration, and Management, 1st Edition** + + :Author: Kenneth Hess + :Publisher: O'Reilly Media + :Date: May, 2023 + :Pages: 246 + :ISBN: 978-1098109035 + :Notes: System administration + .. _ldd3_published: * Title: **Linux Device Drivers, 3rd Edition** diff --git a/Documentation/process/maintainer-handbooks.rst b/Documentation/process/maintainer-handbooks.rst index 9992bfd7eaa3..976391cec528 100644 --- a/Documentation/process/maintainer-handbooks.rst +++ b/Documentation/process/maintainer-handbooks.rst @@ -17,5 +17,6 @@ Contents: maintainer-netdev maintainer-soc + maintainer-soc-clean-dts maintainer-tip maintainer-kvm-x86 diff --git a/Documentation/process/maintainer-netdev.rst b/Documentation/process/maintainer-netdev.rst index 2ab843cde830..c1c732e9748b 100644 --- a/Documentation/process/maintainer-netdev.rst +++ b/Documentation/process/maintainer-netdev.rst @@ -167,6 +167,8 @@ Asking the maintainer for status updates on your patch is a good way to ensure your patch is ignored or pushed to the bottom of the priority list. +.. _Changes requested: + Changes requested ~~~~~~~~~~~~~~~~~ @@ -359,6 +361,10 @@ Make sure you address all the feedback in your new posting. Do not post a new version of the code if the discussion about the previous version is still ongoing, unless directly instructed by a reviewer. +The new version of patches should be posted as a separate thread, +not as a reply to the previous posting. Change log should include a link +to the previous posting (see :ref:`Changes requested`). + Testing ------- diff --git a/Documentation/process/maintainer-soc-clean-dts.rst b/Documentation/process/maintainer-soc-clean-dts.rst new file mode 100644 index 000000000000..1b32430d0cfc --- /dev/null +++ b/Documentation/process/maintainer-soc-clean-dts.rst @@ -0,0 +1,25 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============================================== +SoC Platforms with DTS Compliance Requirements +============================================== + +Overview +-------- + +SoC platforms or subarchitectures should follow all the rules from +Documentation/process/maintainer-soc.rst. This document referenced in +MAINTAINERS impose additional requirements listed below. + +Strict DTS DT Schema and dtc Compliance +--------------------------------------- + +No changes to the SoC platform Devicetree sources (DTS files) should introduce +new ``make dtbs_check W=1`` warnings. Warnings in a new board DTS, which are +results of issues in an included DTSI file, are considered existing, not new +warnings. The platform maintainers have automation in place which should point +out any new warnings. + +If a commit introducing new warnings gets accepted somehow, the resulting +issues shall be fixed in reasonable time (e.g. within one release) or the +commit reverted. diff --git a/Documentation/process/maintainer-soc.rst b/Documentation/process/maintainer-soc.rst index 49f08289d62c..12637530d68f 100644 --- a/Documentation/process/maintainer-soc.rst +++ b/Documentation/process/maintainer-soc.rst @@ -133,8 +133,8 @@ with the dt-bindings that describe the ABI. Please read the section more information on the validation of devicetrees. For new platforms, or additions to existing ones, ``make dtbs_check`` should not -add any new warnings. For RISC-V, as it has the advantage of being a newer -architecture, ``make dtbs_check W=1`` is required to not add any new warnings. +add any new warnings. For RISC-V and Samsung SoC, ``make dtbs_check W=1`` is +required to not add any new warnings. If in any doubt about a devicetree change, reach out to the devicetree maintainers. diff --git a/Documentation/process/researcher-guidelines.rst b/Documentation/process/researcher-guidelines.rst index 9fcfed3c350b..d159cd4f5e5b 100644 --- a/Documentation/process/researcher-guidelines.rst +++ b/Documentation/process/researcher-guidelines.rst @@ -44,6 +44,33 @@ explicit agreement of, and full disclosure to, the individual developers involved. Developers cannot be interacted with/experimented on without consent; this, too, is standard research ethics. +Surveys +======= + +Research often takes the form of surveys sent to maintainers or +contributors. As a general rule, though, the kernel community derives +little value from these surveys. The kernel development process works +because every developer benefits from their participation, even working +with others who have different goals. Responding to a survey, though, is a +one-way demand placed on busy developers with no corresponding benefit to +themselves or to the kernel community as a whole. For this reason, this +method of research is discouraged. + +Kernel community members already receive far too much email and are likely +to perceive survey requests as just another demand on their time. Sending +such requests deprives the community of valuable contributor time and is +unlikely to yield a statistically useful response. + +As an alternative, researchers should consider attending developer events, +hosting sessions where the research project and its benefits to the +participants can be explained, and interacting directly with the community +there. The information received will be far richer than that obtained from +an email survey, and the community will gain from the ability to learn from +your insights as well. + +Patches +======= + To help clarify: sending patches to developers *is* interacting with them, but they have already consented to receiving *good faith contributions*. Sending intentionally flawed/vulnerable patches or diff --git a/Documentation/process/stable-kernel-rules.rst b/Documentation/process/stable-kernel-rules.rst index 51df1197d5ab..41f1e07abfdf 100644 --- a/Documentation/process/stable-kernel-rules.rst +++ b/Documentation/process/stable-kernel-rules.rst @@ -6,30 +6,29 @@ Everything you ever wanted to know about Linux -stable releases Rules on what kind of patches are accepted, and which ones are not, into the "-stable" tree: + - It or an equivalent fix must already exist in Linus' tree (upstream). - It must be obviously correct and tested. - It cannot be bigger than 100 lines, with context. - - It must fix only one thing. - - It must fix a real bug that bothers people (not a, "This could be a - problem..." type thing). - - It must fix a problem that causes a build error (but not for things - marked CONFIG_BROKEN), an oops, a hang, data corruption, a real - security issue, or some "oh, that's not good" issue. In short, something - critical. - - Serious issues as reported by a user of a distribution kernel may also - be considered if they fix a notable performance or interactivity issue. - As these fixes are not as obvious and have a higher risk of a subtle - regression they should only be submitted by a distribution kernel - maintainer and include an addendum linking to a bugzilla entry if it - exists and additional information on the user-visible impact. - - New device IDs and quirks are also accepted. - - No "theoretical race condition" issues, unless an explanation of how the - race can be exploited is also provided. - - It cannot contain any "trivial" fixes in it (spelling changes, - whitespace cleanups, etc). - It must follow the :ref:`Documentation/process/submitting-patches.rst <submittingpatches>` rules. - - It or an equivalent fix must already exist in Linus' tree (upstream). + - It must either fix a real bug that bothers people or just add a device ID. + To elaborate on the former: + + - It fixes a problem like an oops, a hang, data corruption, a real security + issue, a hardware quirk, a build error (but not for things marked + CONFIG_BROKEN), or some "oh, that's not good" issue. + - Serious issues as reported by a user of a distribution kernel may also + be considered if they fix a notable performance or interactivity issue. + As these fixes are not as obvious and have a higher risk of a subtle + regression they should only be submitted by a distribution kernel + maintainer and include an addendum linking to a bugzilla entry if it + exists and additional information on the user-visible impact. + - No "This could be a problem..." type of things like a "theoretical race + condition", unless an explanation of how the bug can be exploited is also + provided. + - No "trivial" fixes without benefit for users (spelling changes, whitespace + cleanups, etc). Procedure for submitting patches to the -stable tree @@ -41,111 +40,142 @@ Procedure for submitting patches to the -stable tree process but should follow the procedures in :ref:`Documentation/process/security-bugs.rst <securitybugs>`. -For all other submissions, choose one of the following procedures ------------------------------------------------------------------ +There are three options to submit a change to -stable trees: + + 1. Add a 'stable tag' to the description of a patch you then submit for + mainline inclusion. + 2. Ask the stable team to pick up a patch already mainlined. + 3. Submit a patch to the stable team that is equivalent to a change already + mainlined. + +The sections below describe each of the options in more detail. + +:ref:`option_1` is **strongly** preferred, it is the easiest and most common. +:ref:`option_2` is mainly meant for changes where backporting was not considered +at the time of submission. :ref:`option_3` is an alternative to the two earlier +options for cases where a mainlined patch needs adjustments to apply in older +series (for example due to API changes). + +When using option 2 or 3 you can ask for your change to be included in specific +stable series. When doing so, ensure the fix or an equivalent is applicable, +submitted, or already present in all newer stable trees still supported. This is +meant to prevent regressions that users might later encounter on updating, if +e.g. a fix merged for 5.19-rc1 would be backported to 5.10.y, but not to 5.15.y. .. _option_1: Option 1 ******** -To have the patch automatically included in the stable tree, add the tag +To have a patch you submit for mainline inclusion later automatically picked up +for stable trees, add the tag .. code-block:: none -in the sign-off area. Once the patch is merged it will be applied to -the stable tree without anything else needing to be done by the author -or subsystem maintainer. +in the sign-off area. Once the patch is mainlined it will be applied to the +stable tree without anything else needing to be done by the author or +subsystem maintainer. -.. _option_2: +To sent additional instructions to the stable team, use a shell-style inline +comment: -Option 2 -******** + * To specify any additional patch prerequisites for cherry picking use the + following format in the sign-off area: -After the patch has been merged to Linus' tree, send an email to [email protected] containing the subject of the patch, the commit ID, -why you think it should be applied, and what kernel version you wish it to -be applied to. + .. code-block:: none -.. _option_3: + Cc: <[email protected]> # 3.3.x: a1f84a3: sched: Check for idle + Cc: <[email protected]> # 3.3.x: 1b9508f: sched: Rate-limit newidle + Cc: <[email protected]> # 3.3.x: fd21073: sched: Fix affinity logic + Cc: <[email protected]> # 3.3.x + Signed-off-by: Ingo Molnar <[email protected]> -Option 3 -******** + The tag sequence has the meaning of: -Send the patch, after verifying that it follows the above rules, to [email protected]. You must note the upstream commit ID in the -changelog of your submission, as well as the kernel version you wish -it to be applied to. + .. code-block:: none -:ref:`option_1` is **strongly** preferred, is the easiest and most common. -:ref:`option_2` and :ref:`option_3` are more useful if the patch isn't deemed -worthy at the time it is applied to a public git tree (for instance, because -it deserves more regression testing first). :ref:`option_3` is especially -useful if the original upstream patch needs to be backported (for example -the backport needs some special handling due to e.g. API changes). + git cherry-pick a1f84a3 + git cherry-pick 1b9508f + git cherry-pick fd21073 + git cherry-pick <this commit> -Note that for :ref:`option_3`, if the patch deviates from the original -upstream patch (for example because it had to be backported) this must be very -clearly documented and justified in the patch description. + * For patches that may have kernel version prerequisites specify them using + the following format in the sign-off area: -The upstream commit ID must be specified with a separate line above the commit -text, like this: + .. code-block:: none -.. code-block:: none + Cc: <[email protected]> # 3.3.x - commit <sha1> upstream. + The tag has the meaning of: -or alternatively: + .. code-block:: none -.. code-block:: none + git cherry-pick <this commit> - [ Upstream commit <sha1> ] + For each "-stable" tree starting with the specified version. -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: + Note, such tagging is unnecessary if the stable team can derive the + appropriate versions from Fixes: tags. -.. code-block:: none + * To delay pick up of patches, use the following format: - Cc: <[email protected]> # 3.3.x: a1f84a3: sched: Check for idle - Cc: <[email protected]> # 3.3.x: 1b9508f: sched: Rate-limit newidle - Cc: <[email protected]> # 3.3.x: fd21073: sched: Fix affinity logic - Cc: <[email protected]> # 3.3.x - Signed-off-by: Ingo Molnar <[email protected]> + .. code-block:: none -The tag sequence has the meaning of: + Cc: <[email protected]> # after 4 weeks in mainline -.. code-block:: none + * For any other requests, just add a note to the stable tag. This for example + can be used to point out known problems: - git cherry-pick a1f84a3 - git cherry-pick 1b9508f - git cherry-pick fd21073 - git cherry-pick <this commit> + .. code-block:: none + + Cc: <[email protected]> # see patch description, needs adjustments for <= 6.3 + +.. _option_2: + +Option 2 +******** + +If the patch already has been merged to mainline, send an email to [email protected] containing the subject of the patch, the commit ID, +why you think it should be applied, and what kernel versions you wish it to +be applied to. + +.. _option_3: -Also, some patches may have kernel version prerequisites. This can be -specified in the following format in the sign-off area: +Option 3 +******** + +Send the patch, after verifying that it follows the above rules, to [email protected] and mention the kernel versions you wish it to be applied +to. When doing so, you must note the upstream commit ID in the changelog of your +submission with a separate line above the commit text, like this: .. code-block:: none - Cc: <[email protected]> # 3.3.x + commit <sha1> upstream. -The tag has the meaning of: +or alternatively: .. code-block:: none - git cherry-pick <this commit> + [ Upstream commit <sha1> ] + +If the submitted patch deviates from the original upstream patch (for example +because it had to be adjusted for the older API), this must be very clearly +documented and justified in the patch description. -For each "-stable" tree starting with the specified version. -Following the submission: +Following the submission +------------------------ - - The sender will receive an ACK when the patch has been accepted into the - queue, or a NAK if the patch is rejected. This response might take a few - days, according to the developer's schedules. - - If accepted, the patch will be added to the -stable queue, for review by - other developers and by the relevant subsystem maintainer. +The sender will receive an ACK when the patch has been accepted into the +queue, or a NAK if the patch is rejected. This response might take a few +days, according to the schedules of the stable team members. + +If accepted, the patch will be added to the -stable queue, for review by other +developers and by the relevant subsystem maintainer. Review cycle @@ -174,6 +204,7 @@ Review cycle security kernel team, and not go through the normal review cycle. Contact the kernel security team for more details on this procedure. + Trees ----- |