diff options
Diffstat (limited to 'Documentation/process')
-rw-r--r-- | Documentation/process/coding-style.rst | 2 | ||||
-rw-r--r-- | Documentation/process/contribution-maturity-model.rst | 109 | ||||
-rw-r--r-- | Documentation/process/index.rst | 1 | ||||
-rw-r--r-- | Documentation/process/kernel-docs.rst | 36 | ||||
-rw-r--r-- | Documentation/process/magic-number.rst | 1 | ||||
-rw-r--r-- | Documentation/process/maintainer-netdev.rst | 38 | ||||
-rw-r--r-- | Documentation/process/maintainer-tip.rst | 4 | ||||
-rw-r--r-- | Documentation/process/submitting-patches.rst | 19 |
8 files changed, 189 insertions, 21 deletions
diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst index 007e49ef6cec..6db37a46d305 100644 --- a/Documentation/process/coding-style.rst +++ b/Documentation/process/coding-style.rst @@ -1267,5 +1267,5 @@ gcc internals and indent, all available from https://www.gnu.org/manual/ WG14 is the international standardization working group for the programming language C, URL: http://www.open-std.org/JTC1/SC22/WG14/ -Kernel :ref:`process/coding-style.rst <codingstyle>`, by greg@kroah.com at OLS 2002: +Kernel CodingStyle, by greg@kroah.com at OLS 2002: http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/ diff --git a/Documentation/process/contribution-maturity-model.rst b/Documentation/process/contribution-maturity-model.rst new file mode 100644 index 000000000000..b87ab34de22c --- /dev/null +++ b/Documentation/process/contribution-maturity-model.rst @@ -0,0 +1,109 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======================================== +Linux Kernel Contribution Maturity Model +======================================== + + +Background +========== + +As a part of the 2021 Linux Kernel Maintainers’ Summit, there was a +`discussion <https://lwn.net/Articles/870581/>`_ about the challenges in +recruiting kernel maintainers as well as maintainer succession. Some of +the conclusions from that discussion included that companies which are a +part of the Linux Kernel community need to allow engineers to be +maintainers as part of their job, so they can grow into becoming +respected leaders and eventually, kernel maintainers. To support a +strong talent pipeline, developers should be allowed and encouraged to +take on upstream contributions such as reviewing other people’s patches, +refactoring kernel infrastructure, and writing documentation. + +To that end, the Linux Foundation Technical Advisory Board (TAB) +proposes this Linux Kernel Contribution Maturity Model. These common +expectations for upstream community engagement aim to increase the +influence of individual developers, increase the collaboration of +organizations, and improve the overall health of the Linux Kernel +ecosystem. + +The TAB urges organizations to continuously evaluate their Open Source +maturity model and commit to improvements to align with this model. To +be effective, this evaluation should incorporate feedback from across +the organization, including management and developers at all seniority +levels. In the spirit of Open Source, we encourage organizations to +publish their evaluations and plans to improve their engagement with the +upstream community. + +Level 0 +======= + +* Software Engineers are not allowed to contribute patches to the Linux + kernel. + + +Level 1 +======= + +* Software Engineers are allowed to contribute patches to the Linux + kernel, either as part of their job responsibilities or on their own + time. + +Level 2 +======= + +* Software Engineers are expected to contribute to the Linux Kernel as + part of their job responsibilities. +* Software Engineers will be supported to attend Linux-related + conferences as a part of their job. +* A Software Engineer’s upstream code contributions will be considered + in promotion and performance reviews. + +Level 3 +======= + +* Software Engineers are expected to review patches (including patches + authored by engineers from other companies) as part of their job + responsibilities +* Contributing presentations or papers to Linux-related or academic + conferences (such those organized by the Linux Foundation, Usenix, + ACM, etc.), are considered part of an engineer’s work. +* A Software Engineer’s community contributions will be considered in + promotion and performance reviews. +* Organizations will regularly report metrics of their open source + contributions and track these metrics over time. These metrics may be + published only internally within the organization, or at the + organization’s discretion, some or all may be published externally. + Metrics that are strongly suggested include: + + * The number of upstream kernel contributions by team or organization + (e.g., all people reporting up to a manager, director, or VP). + * The percentage of kernel developers who have made upstream + contributions relative to the total kernel developers in the + organization. + * The time interval between kernels used in the organization’s servers + and/or products, and the publication date of the upstream kernel + upon which the internal kernel is based. + * The number of out-of-tree commits present in internal kernels. + +Level 4 +======= + +* Software Engineers are encouraged to spend a portion of their work + time focused on Upstream Work, which is defined as reviewing patches, + serving on program committees, improving core project infrastructure + such as writing or maintaining tests, upstream tech debt reduction, + writing documentation, etc. +* Software Engineers are supported in helping to organize Linux-related + conferences. +* Organizations will consider community member feedback in official + performance reviews. + +Level 5 +======= + +* Upstream kernel development is considered a formal job position, with + at least a third of the engineer’s time spent doing Upstream Work. +* Organizations will actively seek out community member feedback as a + factor in official performance reviews. +* Organizations will regularly report internally on the ratio of + Upstream Work to work focused on directly pursuing business goals. diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst index 565df595152e..b501cd977053 100644 --- a/Documentation/process/index.rst +++ b/Documentation/process/index.rst @@ -57,6 +57,7 @@ Other guides to the community that are of interest to most developers are: deprecated maintainers researcher-guidelines + contribution-maturity-model These are some overall technical guides that have been put here for now for lack of a better place. diff --git a/Documentation/process/kernel-docs.rst b/Documentation/process/kernel-docs.rst index 1c6e2ab92f4e..46f927aae6eb 100644 --- a/Documentation/process/kernel-docs.rst +++ b/Documentation/process/kernel-docs.rst @@ -75,13 +75,39 @@ On-line docs Published books --------------- + * Title: **Linux Kernel Debugging: Leverage proven tools and advanced techniques to effectively debug Linux kernels and kernel modules** + + :Author: Kaiwan N Billimoria + :Publisher: Packt Publishing Ltd + :Date: August, 2022 + :Pages: 638 + :ISBN: 978-1801075039 + :Notes: Debugging book + * Title: **Linux Kernel Programming: A Comprehensive Guide to Kernel Internals, Writing Kernel Modules, and Kernel Synchronization** - :Author: Kaiwan N. Billimoria - :Publisher: Packt Publishing Ltd - :Date: 2021 - :Pages: 754 - :ISBN: 978-1789953435 + :Author: Kaiwan N Billimoria + :Publisher: Packt Publishing Ltd + :Date: March, 2021 + :Pages: 754 + :ISBN: 978-1789953435 + + * Title: **Linux Kernel Programming Part 2 - Char Device Drivers and Kernel Synchronization: Create user-kernel interfaces, work with peripheral I/O, and handle hardware interrupts** + + :Author: Kaiwan N Billimoria + :Publisher: Packt Publishing Ltd + :Date: March, 2021 + :Pages: 452 + :ISBN: 978-1801079518 + + * Title: **Linux System Programming: Talking Directly to the Kernel and C Library** + + :Author: Robert Love + :Publisher: O'Reilly Media + :Date: June, 2013 + :Pages: 456 + :ISBN: 978-1449339531 + :Notes: Foundational book * Title: **Linux Kernel Development, 3rd Edition** diff --git a/Documentation/process/magic-number.rst b/Documentation/process/magic-number.rst index 64b5948fc1d4..7029c3c084ee 100644 --- a/Documentation/process/magic-number.rst +++ b/Documentation/process/magic-number.rst @@ -72,7 +72,6 @@ PG_MAGIC 'P' pg_{read,write}_hdr ``include/linux/ APM_BIOS_MAGIC 0x4101 apm_user ``arch/x86/kernel/apm_32.c`` FASYNC_MAGIC 0x4601 fasync_struct ``include/linux/fs.h`` SLIP_MAGIC 0x5302 slip ``drivers/net/slip.h`` -MGSLPC_MAGIC 0x5402 mgslpc_info ``drivers/char/pcmcia/synclink_cs.c`` BAYCOM_MAGIC 0x19730510 baycom_state ``drivers/net/baycom_epp.c`` HDLCDRV_MAGIC 0x5ac6e778 hdlcdrv_state ``include/linux/hdlcdrv.h`` KV_MAGIC 0x5f4b565f kernel_vars_s ``arch/mips/include/asm/sn/klkernvars.h`` diff --git a/Documentation/process/maintainer-netdev.rst b/Documentation/process/maintainer-netdev.rst index 4a75686d35ab..f73ac9e175a8 100644 --- a/Documentation/process/maintainer-netdev.rst +++ b/Documentation/process/maintainer-netdev.rst @@ -109,6 +109,8 @@ Finally, the vX.Y gets released, and the whole cycle starts over. netdev patch review ------------------- +.. _patch_status: + Patch status ~~~~~~~~~~~~ @@ -143,6 +145,33 @@ 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 +~~~~~~~~~~~~~~~~~ + +Patches :ref:`marked<patch_status>` as ``Changes Requested`` need +to be revised. The new version should come with a change log, +preferably including links to previous postings, for example:: + + [PATCH net-next v3] net: make cows go moo + + Even users who don't drink milk appreciate hearing the cows go "moo". + + The amount of mooing will depend on packet rate so should match + the diurnal cycle quite well. + + Signed-of-by: Joe Defarmer <joe@barn.org> + --- + v3: + - add a note about time-of-day mooing fluctuation to the commit message + v2: https://lore.kernel.org/netdev/123themessageid@barn.org/ + - fix missing argument in kernel doc for netif_is_bovine() + - fix memory leak in netdev_register_cow() + v1: https://lore.kernel.org/netdev/456getstheclicks@barn.org/ + +The commit message should be revised to answer any questions reviewers +had to ask in previous discussions. Occasionally the update of +the commit message will be the only change in the new version. + Partial resends ~~~~~~~~~~~~~~~ @@ -155,11 +184,18 @@ Handling misapplied patches Occasionally a patch series gets applied before receiving critical feedback, or the wrong version of a series gets applied. -There is no revert possible, once it is pushed out, it stays like that. + +Making the patch disappear once it is pushed out is not possible, the commit +history in netdev trees is immutable. Please send incremental versions on top of what has been merged in order to fix the patches the way they would look like if your latest patch series was to be merged. +In cases where full revert is needed the revert has to be submitted +as a patch to the list with a commit message explaining the technical +problems with the reverted commit. Reverts should be used as a last resort, +when original change is completely wrong; incremental fixes are preferred. + Stable tree ~~~~~~~~~~~ diff --git a/Documentation/process/maintainer-tip.rst b/Documentation/process/maintainer-tip.rst index 572a3289c9cb..178c95fd17dc 100644 --- a/Documentation/process/maintainer-tip.rst +++ b/Documentation/process/maintainer-tip.rst @@ -128,8 +128,8 @@ uppercase letter and should be written in imperative tone. Changelog ^^^^^^^^^ -The general rules about changelogs in the process documentation, see -:ref:`Documentation/process/ <submittingpatches>`, apply. +The general rules about changelogs in the :ref:`Submitting patches guide +<describe_changes>`, apply. The tip tree maintainers set value on following these rules, especially on the request to write changelogs in imperative mood and not impersonating diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst index 12d58ddc2b8a..486875fd73c0 100644 --- a/Documentation/process/submitting-patches.rst +++ b/Documentation/process/submitting-patches.rst @@ -231,20 +231,17 @@ patch. Select the recipients for your patch ------------------------------------ -You should always copy the appropriate subsystem maintainer(s) on any patch -to code that they maintain; look through the MAINTAINERS file and the -source code revision history to see who those maintainers are. The -script scripts/get_maintainer.pl can be very useful at this step (pass paths to -your patches as arguments to scripts/get_maintainer.pl). If you cannot find a +You should always copy the appropriate subsystem maintainer(s) and list(s) on +any patch to code that they maintain; look through the MAINTAINERS file and the +source code revision history to see who those maintainers are. The script +scripts/get_maintainer.pl can be very useful at this step (pass paths to your +patches as arguments to scripts/get_maintainer.pl). If you cannot find a maintainer for the subsystem you are working on, Andrew Morton (akpm@linux-foundation.org) serves as a maintainer of last resort. -You should also normally choose at least one mailing list to receive a copy -of your patch set. linux-kernel@vger.kernel.org should be used by default -for all patches, but the volume on that list has caused a number of -developers to tune it out. Look in the MAINTAINERS file for a -subsystem-specific list; your patch will probably get more attention there. -Please do not spam unrelated lists, though. +linux-kernel@vger.kernel.org should be used by default for all patches, but the +volume on that list has caused a number of developers to tune it out. Please +do not spam unrelated lists and unrelated people, though. Many kernel-related lists are hosted on vger.kernel.org; you can find a list of them at http://vger.kernel.org/vger-lists.html. There are |