diff options
Diffstat (limited to 'Documentation/maintainer')
| -rw-r--r-- | Documentation/maintainer/configure-git.rst | 36 | ||||
| -rw-r--r-- | Documentation/maintainer/feature-and-driver-maintainers.rst | 155 | ||||
| -rw-r--r-- | Documentation/maintainer/index.rst | 1 | ||||
| -rw-r--r-- | Documentation/maintainer/pull-requests.rst | 4 |
4 files changed, 172 insertions, 24 deletions
diff --git a/Documentation/maintainer/configure-git.rst b/Documentation/maintainer/configure-git.rst index ec0ddfb9cdd3..0a36831814ea 100644 --- a/Documentation/maintainer/configure-git.rst +++ b/Documentation/maintainer/configure-git.rst @@ -1,35 +1,31 @@ -.. _configuregit: - -Configure Git -============= +Configuring Git +=============== This chapter describes maintainer level git configuration. -Tagged branches used in :ref:`Documentation/maintainer/pull-requests.rst -<pullrequests>` should be signed with the developers public GPG key. Signed -tags can be created by passing the ``-u`` flag to ``git tag``. However, -since you would *usually* use the same key for the same project, you can -set it once with -:: +Tagged branches used in pull requests (see +Documentation/maintainer/pull-requests.rst) should be signed with the +developers public GPG key. Signed tags can be created by passing +``-u <key-id>`` to ``git tag``. However, since you would *usually* use the same +key for the project, you can set it in the configuration and use the ``-s`` +flag. To set the default ``key-id`` use:: git config user.signingkey "keyname" -Alternatively, edit your ``.git/config`` or ``~/.gitconfig`` file by hand: -:: +Alternatively, edit your ``.git/config`` or ``~/.gitconfig`` file by hand:: [user] name = Jane Developer email = jd@domain.org signingkey = jd@domain.org -You may need to tell ``git`` to use ``gpg2`` -:: +You may need to tell ``git`` to use ``gpg2``:: [gpg] program = /path/to/gpg2 -You may also like to tell ``gpg`` which ``tty`` to use (add to your shell rc file) -:: +You may also like to tell ``gpg`` which ``tty`` to use (add to your shell +rc file):: export GPG_TTY=$(tty) @@ -37,20 +33,18 @@ You may also like to tell ``gpg`` which ``tty`` to use (add to your shell rc fil Creating commit links to lore.kernel.org ---------------------------------------- -The web site http://lore.kernel.org is meant as a grand archive of all mail +The web site https://lore.kernel.org is meant as a grand archive of all mail list traffic concerning or influencing the kernel development. Storing archives of patches here is a recommended practice, and when a maintainer applies a patch to a subsystem tree, it is a good idea to provide a Link: tag with a reference back to the lore archive so that people that browse the commit history can find related discussions and rationale behind a certain change. -The link tag will look like this: +The link tag will look like this:: Link: https://lore.kernel.org/r/<message-id> This can be configured to happen automatically any time you issue ``git am`` -by adding the following hook into your git: - -.. code-block:: none +by adding the following hook into your git:: $ git config am.messageid true $ cat >.git/hooks/applypatch-msg <<'EOF' diff --git a/Documentation/maintainer/feature-and-driver-maintainers.rst b/Documentation/maintainer/feature-and-driver-maintainers.rst new file mode 100644 index 000000000000..f04cc183e1de --- /dev/null +++ b/Documentation/maintainer/feature-and-driver-maintainers.rst @@ -0,0 +1,155 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============================== +Feature and driver maintainers +============================== + +The term "maintainer" spans a very wide range of levels of engagement +from people handling patches and pull requests as almost a full time job +to people responsible for a small feature or a driver. + +Unlike most of the chapter, this section is meant for the latter (more +populous) group. It provides tips and describes the expectations and +responsibilities of maintainers of a small(ish) section of the code. + +Drivers and alike most often do not have their own mailing lists and +git trees but instead send and review patches on the list of a larger +subsystem. + +Responsibilities +================ + +The amount of maintenance work is usually proportional to the size +and popularity of the code base. Small features and drivers should +require relatively small amount of care and feeding. Nonetheless +when the work does arrive (in form of patches which need review, +user bug reports etc.) it has to be acted upon promptly. +Even when a particular driver only sees one patch a month, or a quarter, +a subsystem could well have a hundred such drivers. Subsystem +maintainers cannot afford to wait a long time to hear from reviewers. + +The exact expectations on the response time will vary by subsystem. +The patch review SLA the subsystem had set for itself can sometimes +be found in the subsystem documentation. Failing that as a rule of thumb +reviewers should try to respond quicker than what is the usual patch +review delay of the subsystem maintainer. The resulting expectations +may range from two working days for fast-paced subsystems (e.g. networking) +to as long as a few weeks in slower moving parts of the kernel. + +Mailing list participation +-------------------------- + +Linux kernel uses mailing lists as the primary form of communication. +Maintainers must be subscribed and follow the appropriate subsystem-wide +mailing list. Either by subscribing to the whole list or using more +modern, selective setup like +`lei <https://people.kernel.org/monsieuricon/lore-lei-part-1-getting-started>`_. + +Maintainers must know how to communicate on the list (plain text, no invasive +legal footers, no top posting, etc.) + +Reviews +------- + +Maintainers must review *all* patches touching exclusively their drivers, +no matter how trivial. If the patch is a tree wide change and modifies +multiple drivers - whether to provide a review is left to the maintainer. + +When there are multiple maintainers for a piece of code an ``Acked-by`` +or ``Reviewed-by`` tag (or review comments) from a single maintainer is +enough to satisfy this requirement. + +If the review process or validation for a particular change will take longer +than the expected review timeline for the subsystem, maintainer should +reply to the submission indicating that the work is being done, and when +to expect full results. + +Refactoring and core changes +---------------------------- + +Occasionally core code needs to be changed to improve the maintainability +of the kernel as a whole. Maintainers are expected to be present and +help guide and test changes to their code to fit the new infrastructure. + +Bug reports +----------- + +Maintainers must ensure severe problems in their code reported to them +are resolved in a timely manner: regressions, kernel crashes, kernel warnings, +compilation errors, lockups, data loss, and other bugs of similar scope. + +Maintainers furthermore should respond to reports about other kinds of +bugs as well, if the report is of reasonable quality or indicates a +problem that might be severe -- especially if they have *Supported* +status of the codebase in the MAINTAINERS file. + +Selecting the maintainer +======================== + +The previous section described the expectations of the maintainer, +this section provides guidance on selecting one and describes common +misconceptions. + +The author +---------- + +Most natural and common choice of a maintainer is the author of the code. +The author is intimately familiar with the code, so it is the best person +to take care of it on an ongoing basis. + +That said, being a maintainer is an active role. The MAINTAINERS file +is not a list of credits (in fact a separate CREDITS file exists), +it is a list of those who will actively help with the code. +If the author does not have the time, interest or ability to maintain +the code, a different maintainer must be selected. + +Multiple maintainers +-------------------- + +Modern best practices dictate that there should be at least two maintainers +for any piece of code, no matter how trivial. It spreads the burden, helps +people take vacations and prevents burnout, trains new members of +the community etc. etc. Even when there is clearly one perfect candidate, +another maintainer should be found. + +Maintainers must be human, therefore, it is not acceptable to add a mailing +list or a group email as a maintainer. Trust and understanding are the +foundation of kernel maintenance and one cannot build trust with a mailing +list. Having a mailing list *in addition* to humans is perfectly fine. + +Corporate structures +-------------------- + +To an outsider the Linux kernel may resemble a hierarchical organization +with Linus as the CEO. While the code flows in a hierarchical fashion, +the corporate template does not apply here. Linux is an anarchy held +together by (rarely expressed) mutual respect, trust and convenience. + +All that is to say that managers almost never make good maintainers. +The maintainer position more closely matches an on-call rotation +than a position of power. + +The following characteristics of a person selected as a maintainer +are clear red flags: + + - unknown to the community, never sent an email to the list before + - did not author any of the code + - (when development is contracted) works for a company which paid + for the development rather than the company which did the work + +Non compliance +============== + +Subsystem maintainers may remove inactive maintainers from the MAINTAINERS +file. If the maintainer was a significant author or played an important +role in the development of the code, they should be moved to the CREDITS file. + +Removing an inactive maintainer should not be seen as a punitive action. +Having an inactive maintainer has a real cost as all developers have +to remember to include the maintainers in discussions and subsystem +maintainers spend brain power figuring out how to solicit feedback. + +Subsystem maintainers may remove code for lacking maintenance. + +Subsystem maintainers may refuse accepting code from companies +which repeatedly neglected their maintainership duties. diff --git a/Documentation/maintainer/index.rst b/Documentation/maintainer/index.rst index 3e03283c144e..eeee27f8b18c 100644 --- a/Documentation/maintainer/index.rst +++ b/Documentation/maintainer/index.rst @@ -9,6 +9,7 @@ additions to this manual. .. toctree:: :maxdepth: 2 + feature-and-driver-maintainers configure-git rebasing-and-merging pull-requests diff --git a/Documentation/maintainer/pull-requests.rst b/Documentation/maintainer/pull-requests.rst index e072de60ccb0..00b200facf67 100644 --- a/Documentation/maintainer/pull-requests.rst +++ b/Documentation/maintainer/pull-requests.rst @@ -1,5 +1,3 @@ -.. _pullrequests: - Creating Pull Requests ====================== @@ -41,7 +39,7 @@ named ``char-misc-next``, you would be using the following command:: that will create a signed tag called ``char-misc-4.15-rc1`` based on the last commit in the ``char-misc-next`` branch, and sign it with your gpg key -(see :ref:`Documentation/maintainer/configure-git.rst <configuregit>`). +(see Documentation/maintainer/configure-git.rst). Linus will only accept pull requests based on a signed tag. Other maintainers may differ. |