Skip to contentSkip to conversation

docs: maintainer: document expectations of small time maintainers

PATCH Superseded Jakub Kicinski 9 participants 11 messages Jul 18, 2023 – Jul 19, 2023

Subsystems (4)

v2 of 3 Superseded Latest is v3 →

lore
Share & tools
lore

Jakub Kicinski

author maintainer
#0 lore raw

PATCH v2 1/1 docs: maintainer: document expectations of small time maintainers

We appear to have a gap in our process docs. We go into detail on how to contribute code to the kernel, and how to be a subsystem maintainer. I can't find any docs directed towards the thousands of small scale maintainers, like folks maintaining a single driver or a single network protocol.

Document our expectations and best practices. I'm hoping this doc will be particularly useful to set expectations with HW vendors.

---
v2:
- use Thorsten's wording for bug fixing requirements
- put more words into the review/response timeline expectations
v1: https://lore.kernel.org/all/[email protected]/

---
 .../feature-and-driver-maintainers.rst        | 155 ++++++++++++++++++
 Documentation/maintainer/index.rst            |   1 +
 2 files changed, 156 insertions(+)
 create mode 100644 Documentation/maintainer/feature-and-driver-maintainers.rst
Documentation/maintainer/feature-and-driver-maintainers.rst new file +155 -0
new file mode 100644
index 000000000000..7064b5de076d
@@ -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.
+
+Driver 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 single 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.
+
+There should be multiple maintainers for any piece of code, an ``Acked-by``
+or ``Reviewed-by`` tag (or review comments) from a single maintainer is
+enough to satisfy this requirement.
+
+If 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 kind 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 decribes 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, however, 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.
+
+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 have 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 developeres 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.
Documentation/maintainer/index.rst +1 -0
index 3e03283c144e..eeee27f8b18c 100644
@@ -9,6 +9,7 @@ additions to this manual.
 .. toctree::
    :maxdepth: 2
 
+   feature-and-driver-maintainers
    configure-git
    rebasing-and-merging
    pull-requests
Signature · 1 line
2.41.0
Reviewed-by on v2 1/1
#1 lore raw

Documentation/maintainer/feature-and-driver-maintainers.rst line 90

Quoted 5 lines
Documentation/maintainer/feature-and-driver-maintainers.rst new file +5 -0
+Selecting the maintainer
+========================
+
+The previous section described the expectations of the maintainer,
+this section provides guidance on selecting one and decribes common

s/decribes/describes

Review

Quoted 2 lines
(quoted diff) +2 -0
+Maintainers must be human, however, it is not acceptable to add a mailing
+list or a group email as a maintainer.

I would probably replace however, with therefore.

Documentation/maintainer/feature-and-driver-maintainers.rst line 148

Quoted 2 lines
Documentation/maintainer/feature-and-driver-maintainers.rst new file +2 -0
+Removing an inactive maintainer should not be seen as a punitive action.
+Having an inactive maintainer has a real cost as all developeres have

Too many e's in developeres

Otherwise:

Andrew

Reviewed-by on v2 1/1
#2 lore raw
In reply to Jakub Kicinski
Quoted 10 lines · Jakub Kicinski

We appear to have a gap in our process docs. We go into detail on how to contribute code to the kernel, and how to be a subsystem maintainer. I can't find any docs directed towards the thousands of small scale maintainers, like folks maintaining a single driver or a single network protocol.

Document our expectations and best practices. I'm hoping this doc will be particularly useful to set expectations with HW vendors.

Looks good to me, thanks for writing this up:

Reviewed-by on v2 1/1
#3 lore raw
In reply to Jakub Kicinski
Quoted 10 lines · Jakub Kicinski

We appear to have a gap in our process docs. We go into detail on how to contribute code to the kernel, and how to be a subsystem maintainer. I can't find any docs directed towards the thousands of small scale maintainers, like folks maintaining a single driver or a single network protocol.

Document our expectations and best practices. I'm hoping this doc will be particularly useful to set expectations with HW vendors.

Best regards,
Krzysztof

#4 lore raw
In reply to Jakub Kicinski

On 2023-07-18 08:58 -0700, Jakub Kicinski wrote:
[...]

Documentation/maintainer/feature-and-driver-maintainers.rst line 60

Quoted 10 lines
Documentation/maintainer/feature-and-driver-maintainers.rst new file +10 -0
+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.
+
+There should be multiple maintainers for any piece of code, an ``Acked-by``
+or ``Reviewed-by`` tag (or review comments) from a single maintainer is
+enough to satisfy this requirement.

This sentence seems strange. Were the first two words swapped?

Given the latter part of the document which recommends to have multiple maintainers, maybe this sentence could begin with "When there are multiple maintainers for a piece of code". That sounds less speculative.

[...]

Documentation/maintainer/feature-and-driver-maintainers.rst line 145

Quoted 6 lines
Documentation/maintainer/feature-and-driver-maintainers.rst new file +6 -0
+Non compliance
+==============
+
+Subsystem maintainers may remove inactive maintainers from the MAINTAINERS
+file. If the maintainer was a significant author or have played an important
+role in the development of the code they should be moved to the CREDITS 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.

Reviewed-by on v2 1/1
#5 lore raw
In reply to Jakub Kicinski
Quoted 5 lines · Jakub Kicinski

We appear to have a gap in our process docs. We go into detail on how to contribute code to the kernel, and how to be a subsystem maintainer. I can't find any docs directed towards the thousands of small scale maintainers, like folks maintaining a single driver or a single network protocol.

I'm not super comfortable with all of the musts here but this is probably fine so

One note:

Documentation/maintainer/feature-and-driver-maintainers.rst line 118

Quoted 4 lines
Documentation/maintainer/feature-and-driver-maintainers.rst new file +4 -0
+Maintainers must be human, however, 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.

If you're revising this I'd add a note about the L: tag in MAINTAINERS here, or possibly just adding a list in addition to humans. It is sensible and often helpful for companies to want to get mail copied to a wider distribution list internally but they're not really what we mean by list since external people typically can't join them.

author maintainer
#6 lore raw
Quoted 10 lines · On Tue, 18 Jul 2023 20:55:37 +0100 Mark Brown wrote:

Documentation/maintainer/feature-and-driver-maintainers.rst line 118

Quoted 4 lines
Documentation/maintainer/feature-and-driver-maintainers.rst new file +4 -0
+Maintainers must be human, however, 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.  

If you're revising this I'd add a note about the L: tag in MAINTAINERS here, or possibly just adding a list in addition to humans. It is sensible and often helpful for companies to want to get mail copied to a wider distribution list internally but they're not really what we mean by list since external people typically can't join them.

👍️ Added: "Having a mailing list *in addition* to humans is perfectly fine."

#7 lore raw
In reply to Jakub Kicinski
Quoted 42 lines · Jakub Kicinski

We appear to have a gap in our process docs. We go into detail on how to contribute code to the kernel, and how to be a subsystem maintainer. I can't find any docs directed towards the thousands of small scale maintainers, like folks maintaining a single driver or a single network protocol.

Document our expectations and best practices. I'm hoping this doc will be particularly useful to set expectations with HW vendors.

---
v2:
- use Thorsten's wording for bug fixing requirements
- put more words into the review/response timeline expectations
v1: https://lore.kernel.org/all/[email protected]/

---
  .../feature-and-driver-maintainers.rst        | 155 ++++++++++++++++++
  Documentation/maintainer/index.rst            |   1 +
  2 files changed, 156 insertions(+)

create mode 100644 Documentation/maintainer/feature-and-driver-maintainers.rst

Documentation/maintainer/feature-and-driver-maintainers.rst new file +5 -0
new file mode 100644
index 000000000000..7064b5de076d
@@ -0,0 +1,155 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+==============================
+Feature and driver maintainers
+==============================

Documentation/maintainer/feature-and-driver-maintainers.rst line 15

Quoted 10 lines
Documentation/maintainer/feature-and-driver-maintainers.rst new file +10 -0
+
+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.
+
+Driver and alike most often do not have their own mailing lists and

s/Driver/Drivers/

Documentation/maintainer/feature-and-driver-maintainers.rst line 27

Quoted 12 lines
Documentation/maintainer/feature-and-driver-maintainers.rst new file +12 -0
+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 single driver only sees one patch a month, or a quarter,

s/when single/when a particular/

Quoted 25 lines
Documentation/maintainer/feature-and-driver-maintainers.rst new file +25 -0
+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
+-------

Documentation/maintainer/feature-and-driver-maintainers.rst line 62

Quoted 10 lines
Documentation/maintainer/feature-and-driver-maintainers.rst new file +10 -0
+
+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.
+
+There should be multiple maintainers for any piece of code, an ``Acked-by``
+or ``Reviewed-by`` tag (or review comments) from a single maintainer is
+enough to satisfy this requirement.
+
+If review process or validation for a particular change will take longer

s/If review/If the review/

Quoted 9 lines
Documentation/maintainer/feature-and-driver-maintainers.rst new file +9 -0
+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

Documentation/maintainer/feature-and-driver-maintainers.rst line 81

Quoted 10 lines
Documentation/maintainer/feature-and-driver-maintainers.rst new file +10 -0
+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 kind of

s/kind/kinds/

Documentation/maintainer/feature-and-driver-maintainers.rst line 90

Quoted 9 lines
Documentation/maintainer/feature-and-driver-maintainers.rst new file +9 -0
+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 decribes common

s/decribes/describes/

Quoted 26 lines
Documentation/maintainer/feature-and-driver-maintainers.rst new file +26 -0
+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, however, it is not acceptable to add a mailing
+list or a group email as a maintainer. Trust and understanding are the

Documentation/maintainer/feature-and-driver-maintainers.rst line 126

Quoted 10 lines
Documentation/maintainer/feature-and-driver-maintainers.rst new file +10 -0
+foundation of kernel maintenance and one cannot build trust with a mailing
+list.
+
+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.

:-)
I definitely respect the amount of time and effort you put into the job.

Quoted 12 lines
Documentation/maintainer/feature-and-driver-maintainers.rst new file +12 -0
+
+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

Documentation/maintainer/feature-and-driver-maintainers.rst line 148

Quoted 10 lines
Documentation/maintainer/feature-and-driver-maintainers.rst new file +10 -0
+
+Non compliance
+==============
+
+Subsystem maintainers may remove inactive maintainers from the MAINTAINERS
+file. If the maintainer was a significant author or have 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 developeres have

s/developeres/developers/

Thanks,
sln

Quoted 23 lines
Documentation/maintainer/feature-and-driver-maintainers.rst new file +7 -0
+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.
Documentation/maintainer/index.rst +1 -1
index 3e03283c144e..eeee27f8b18c 100644
@@ -9,6 +9,7 @@ additions to this manual.
  .. toctree::
     :maxdepth: 2
 
+   feature-and-driver-maintainers
     configure-git
     rebasing-and-merging
     pull-requests
--

2.41.0

Reviewed-by on v2 1/1
#8 lore raw
In reply to Jakub Kicinski
Quoted 29 lines · Jakub Kicinski

We appear to have a gap in our process docs. We go into detail on how to contribute code to the kernel, and how to be a subsystem maintainer. I can't find any docs directed towards the thousands of small scale maintainers, like folks maintaining a single driver or a single network protocol.

Document our expectations and best practices. I'm hoping this doc will be particularly useful to set expectations with HW vendors.

---
v2:
- use Thorsten's wording for bug fixing requirements
- put more words into the review/response timeline expectations
v1: https://lore.kernel.org/all/[email protected]/

---
 .../feature-and-driver-maintainers.rst        | 155 ++++++++++++++++++
 Documentation/maintainer/index.rst            |   1 +
 2 files changed, 156 insertions(+)
 create mode 100644 Documentation/maintainer/feature-and-driver-maintainers.rst

<...>

Documentation/maintainer/feature-and-driver-maintainers.rst line 118

Quoted 4 lines
Documentation/maintainer/feature-and-driver-maintainers.rst new file +4 -0
+Maintainers must be human, however, 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.

+1

Thanks,

#9 lore raw
In reply to Jakub Kicinski
Quoted 6 lines · Jakub Kicinski

We appear to have a gap in our process docs. We go into detail on how to contribute code to the kernel, and how to be a subsystem maintainer. I can't find any docs directed towards the thousands of small scale maintainers, like folks maintaining a single driver or a single network protocol.

I think the split is great. It would be even better if this distinction could be made in MAINTAINERS and then the tools could use that. For example, on treewide changes on Cc subsystem maintainers and skip driver maintainers. The problem right now is Cc'ing everyone quickly hits maillist moderation for too many recipients.

Rob

author maintainer
#10 lore raw
Quoted 11 lines · On Wed, 19 Jul 2023 11:54:53 -0600 Rob Herring wrote:
Quoted 5 lines

We appear to have a gap in our process docs. We go into detail on how to contribute code to the kernel, and how to be a subsystem maintainer. I can't find any docs directed towards the thousands of small scale maintainers, like folks maintaining a single driver or a single network protocol.

I think the split is great. It would be even better if this distinction could be made in MAINTAINERS and then the tools could use that. For example, on treewide changes on Cc subsystem maintainers and skip driver maintainers. The problem right now is Cc'ing everyone quickly hits maillist moderation for too many recipients.

Interesting idea. I wonder how much of this can be accomplished by improvements to get_maintainers and interpreting what we already have. There are inverse annoyances, too, where patches for subsystems get CCed all the way up the hierarchy and including linux-kernel@ for not apparent reason. We have to go sprinkle X: entries in MAINTAINERS currently to prevent it.

In any case, I think that's a bit tangential. I sent a v3 already 'cause people kept reporting the same typoes :)