linux/Documentation/maintainer/index.rst

==========================
Kernel Maintainer Handbook
==========================

This document is the humble beginning of a manual for kernel maintainers.
There is a lot yet to go here!  Please feel free to propose (and write)
additions to this manual.

.. toctree::
   :maxdepth: 2

   configure-git
   rebasing-and-merging
   pull-requests
   maintainer-entry-profile
   modifying-patches
doc: add maintainer book There is currently very little documentation in the kernel on maintainer level tasks. In particular there are no documents on creating pull requests to submit to Linus. Quoting Greg Kroah-Hartman on LKML: Anyway, this actually came up at the kernel summit / maintainer meeting a few weeks ago, in that "how do I make a good pull request to Linus" is something we need to document. Here's what I do, and it seems to work well, so maybe we should turn it into the start of the documentation for how to do it. (quote references: kernel summit, Europe 2017) Create a new kernel documentation book 'how to be a maintainer' (suggested by Jonathan Corbet). Add chapters on 'configuring git' and 'creating a pull request'. Most of the content was written by Linus Torvalds and Greg Kroah-Hartman in discussion on LKML. This is stated at the start of one of the chapters and the original email thread is referenced in 'pull-requests.rst'. Signed-off-by: Tobin C. Harding <me@tobin.cc> Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org> Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> 2017-12-03 23:27:29 +00:00			`==========================`
			`Kernel Maintainer Handbook`
			`==========================`

docs: Add an intro note to the maintainers handbook ...just enough to say what the purpose is and to solicit more contributions. Signed-off-by: Jonathan Corbet <corbet@lwn.net> 2017-12-11 21:46:10 +00:00			`This document is the humble beginning of a manual for kernel maintainers.`
			`There is a lot yet to go here! Please feel free to propose (and write)`
			`additions to this manual.`

doc: add maintainer book There is currently very little documentation in the kernel on maintainer level tasks. In particular there are no documents on creating pull requests to submit to Linus. Quoting Greg Kroah-Hartman on LKML: Anyway, this actually came up at the kernel summit / maintainer meeting a few weeks ago, in that "how do I make a good pull request to Linus" is something we need to document. Here's what I do, and it seems to work well, so maybe we should turn it into the start of the documentation for how to do it. (quote references: kernel summit, Europe 2017) Create a new kernel documentation book 'how to be a maintainer' (suggested by Jonathan Corbet). Add chapters on 'configuring git' and 'creating a pull request'. Most of the content was written by Linus Torvalds and Greg Kroah-Hartman in discussion on LKML. This is stated at the start of one of the chapters and the original email thread is referenced in 'pull-requests.rst'. Signed-off-by: Tobin C. Harding <me@tobin.cc> Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org> Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> 2017-12-03 23:27:29 +00:00			`.. toctree::`
			`:maxdepth: 2`

			`configure-git`
docs: Add a document on repository management Every merge window seems to involve at least one episode where subsystem maintainers don't manage their trees as Linus would like. Document the expectations so that at least he has something to point people to. Acked-by: David Rientjes <rientjes@google.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> 2019-05-28 23:12:51 +00:00			`rebasing-and-merging`
doc: add maintainer book There is currently very little documentation in the kernel on maintainer level tasks. In particular there are no documents on creating pull requests to submit to Linus. Quoting Greg Kroah-Hartman on LKML: Anyway, this actually came up at the kernel summit / maintainer meeting a few weeks ago, in that "how do I make a good pull request to Linus" is something we need to document. Here's what I do, and it seems to work well, so maybe we should turn it into the start of the documentation for how to do it. (quote references: kernel summit, Europe 2017) Create a new kernel documentation book 'how to be a maintainer' (suggested by Jonathan Corbet). Add chapters on 'configuring git' and 'creating a pull request'. Most of the content was written by Linus Torvalds and Greg Kroah-Hartman in discussion on LKML. This is stated at the start of one of the chapters and the original email thread is referenced in 'pull-requests.rst'. Signed-off-by: Tobin C. Harding <me@tobin.cc> Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org> Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> 2017-12-03 23:27:29 +00:00			`pull-requests`
Maintainer Handbook: Maintainer Entry Profile As presented at the 2018 Linux Plumbers conference [1], the Maintainer Entry Profile (formerly Subsystem Profile) is proposed as a way to reduce friction between committers and maintainers and encourage conversations amongst maintainers about common best practices. While coding-style, submit-checklist, and submitting-drivers lay out some common expectations there remain local customs and maintainer preferences that vary by subsystem. The profile contains documentation of some of the common policy questions a contributor might have that are local to the subsystem / device-driver, special considerations for the subsystem, or other guidelines that are otherwise not covered by the top-level process documents. The initial and hopefully non-controversial headings in the profile are: Overview: General introduction to how the subsystem operates Submit Checklist Addendum: Mechanical items that gate submission staging, or other requirements that gate patch acceptance. Key Cycle Dates: - Last -rc for new feature submissions: Expected lead time for submissions - Last -rc to merge features: Deadline for merge decisions Resubmit Cadence: When and preferred method to follow up with the maintainer Note that coding style guidelines are explicitly left out of this list. See Documentation/maintainer/maintainer-entry-profile.rst for more details, and a follow-on example profile for the libnvdimm subsystem. [1]: https://linuxplumbersconf.org/event/2/contributions/59/ Cc: Jonathan Corbet <corbet@lwn.net> Cc: Thomas Gleixner <tglx@linutronix.de> Cc: Mauro Carvalho Chehab <mchehab@kernel.org> Cc: Steve French <stfrench@microsoft.com> Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org> Cc: Linus Torvalds <torvalds@linux-foundation.org> Cc: Tobin C. Harding <me@tobin.cc> Cc: Olof Johansson <olof@lixom.net> Cc: Martin K. Petersen <martin.petersen@oracle.com> Cc: Daniel Vetter <daniel.vetter@ffwll.ch> Cc: Joe Perches <joe@perches.com> Cc: Dmitry Vyukov <dvyukov@google.com> Cc: Alexandre Belloni <alexandre.belloni@bootlin.com> Cc: Paul Walmsley <paul.walmsley@sifive.com> Signed-off-by: Dan Williams <dan.j.williams@intel.com> Link: https://lore.kernel.org/r/157462919309.1729495.10585699280061787229.stgit@dwillia2-desk3.amr.corp.intel.com Signed-off-by: Jonathan Corbet <corbet@lwn.net> 2019-11-24 20:59:53 +00:00			`maintainer-entry-profile`
Documentation/maintainer: rehome sign-off process The repeated sign-offs necessary when a subsystem maintainer modifies an incoming patch has been moved from submitting-patches.rst to Documentation/maintainer, since the affairs of a subsystem maintainer are not especially relevant to someone reading a guide for how to submit their first patch. Signed-off-by: Drew DeVault <sir@cmpwn.com> Link: https://lore.kernel.org/r/20200903160545.83185-4-sir@cmpwn.com Signed-off-by: Jonathan Corbet <corbet@lwn.net> 2020-09-03 16:05:44 +00:00			`modifying-patches`
doc: add maintainer book There is currently very little documentation in the kernel on maintainer level tasks. In particular there are no documents on creating pull requests to submit to Linus. Quoting Greg Kroah-Hartman on LKML: Anyway, this actually came up at the kernel summit / maintainer meeting a few weeks ago, in that "how do I make a good pull request to Linus" is something we need to document. Here's what I do, and it seems to work well, so maybe we should turn it into the start of the documentation for how to do it. (quote references: kernel summit, Europe 2017) Create a new kernel documentation book 'how to be a maintainer' (suggested by Jonathan Corbet). Add chapters on 'configuring git' and 'creating a pull request'. Most of the content was written by Linus Torvalds and Greg Kroah-Hartman in discussion on LKML. This is stated at the start of one of the chapters and the original email thread is referenced in 'pull-requests.rst'. Signed-off-by: Tobin C. Harding <me@tobin.cc> Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org> Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> 2017-12-03 23:27:29 +00:00