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.
Signed-off-by: Jakub Kicinski <[email protected]>
---
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]/
CC: [email protected]
CC: [email protected]
Cc: [email protected]
Cc: [email protected]
Cc: [email protected]
Cc: [email protected]
Cc: [email protected]
Cc: [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
diff --git a/Documentation/maintainer/feature-and-driver-maintainers.rst b/Documentation/maintainer/feature-and-driver-maintainers.rst
new file mode 100644
index 000000000000..7064b5de076d
--- /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.
+
+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.
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
--
2.41.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
> +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.
> +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:
Reviewed-by: Andrew Lunn <[email protected]>
Andrew
On Tue, Jul 18, 2023 at 08:58:14AM -0700, Jakub Kicinski wrote:
> 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.
>
> Signed-off-by: Jakub Kicinski <[email protected]>
Looks good to me, thanks for writing this up:
Reviewed-by: Greg Kroah-Hartman <[email protected]>
On 18/07/2023 17:58, Jakub Kicinski wrote:
> 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.
>
> Signed-off-by: Jakub Kicinski <[email protected]>
Reviewed-by: Krzysztof Kozlowski <[email protected]>
Best regards,
Krzysztof
On 2023-07-18 08:58 -0700, Jakub Kicinski wrote:
[...]
> +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.
[...]
> +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.
On Tue, Jul 18, 2023 at 08:58:14AM -0700, Jakub Kicinski wrote:
> 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
Reviewed-by: Mark Brown <[email protected]>
One note:
> +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.
On 7/18/23 8:58 AM, Jakub Kicinski wrote:
>
> 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.
>
> Signed-off-by: Jakub Kicinski <[email protected]>
> ---
> 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]/
>
> CC: [email protected]
> CC: [email protected]
> Cc: [email protected]
> Cc: [email protected]
> Cc: [email protected]
> Cc: [email protected]
> Cc: [email protected]
> Cc: [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
>
> diff --git a/Documentation/maintainer/feature-and-driver-maintainers.rst b/Documentation/maintainer/feature-and-driver-maintainers.rst
> new file mode 100644
> index 000000000000..7064b5de076d
> --- /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.
> +
> +Driver and alike most often do not have their own mailing lists and
s/Driver/Drivers/
> +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/
> +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
s/If review/If the review/
> +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
s/kind/kinds/
> +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/
> +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.
:-)
I definitely respect the amount of time and effort you put into the job.
> +
> +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
s/developeres/developers/
Thanks,
sln
> +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
> --
> 2.41.0
>
>
On Tue, Jul 18, 2023 at 08:58:14AM -0700, Jakub Kicinski wrote:
> 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.
>
> Signed-off-by: Jakub Kicinski <[email protected]>
> ---
> 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]/
>
> CC: [email protected]
> CC: [email protected]
> Cc: [email protected]
> Cc: [email protected]
> Cc: [email protected]
> Cc: [email protected]
> Cc: [email protected]
> Cc: [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
<...>
> +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,
Reviewed-by: Leon Romanovsky <[email protected]>
On Tue, Jul 18, 2023 at 10:00 AM Jakub Kicinski <[email protected]> wrote:
>
> 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
On Tue, 18 Jul 2023 20:55:37 +0100 Mark Brown wrote:
> > +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."
On Wed, 19 Jul 2023 11:54:53 -0600 Rob Herring wrote:
> > 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 :)