From: Mauro Carvalho Chehab <mchehab@kernel.org>
To: Dan Williams <dan.j.williams@intel.com>
Cc: linux-kernel@vger.kernel.org, vishal.l.verma@intel.com,
ksummit-discuss@lists.linuxfoundation.org,
Greg Kroah-Hartman <gregkh@linuxfoundation.org>,
linux-nvdimm@lists.01.org, Dmitry Vyukov <dvyukov@google.com>,
Steve French <stfrench@microsoft.com>,
"Tobin C. Harding" <me@tobin.cc>
Subject: Re: [Ksummit-discuss] [RFC PATCH 2/3] MAINTAINERS, Handbook: Subsystem Profile
Date: Wed, 14 Nov 2018 21:49:22 -0800 [thread overview]
Message-ID: <20181114214922.07d31676@silica.lan> (raw)
In-Reply-To: <154225760492.2499188.14152986544451112930.stgit@dwillia2-desk3.amr.corp.intel.com>
Em Wed, 14 Nov 2018 20:53:25 -0800
Dan Williams <dan.j.williams@intel.com> escreveu:
> As presented at the 2018 Linux Plumbers conference [1], the Subsystem
> Profile is proposed as a way to reduce friction between committers and
> maintainers and perhaps encourage conversations amongst maintainers
> about best practice policies.
>
> The profile contains short answers to some of the common policy
> questions a contributor might have, or that a maintainer might consider
> formalizing. The current list of maintenance policies is:
>
> Overview: General introduction to maintaining the subsystem
> Core: List of source files considered core
> Leaf: List of source files that consume core functionality
> Patches or Pull requests: Simple statement of expected submission format
> Last -rc for new feature submissions: Expected lead time for submissions
> Last -rc to merge features: Deadline for merge decisions
> Non-author Ack / Review Tags Required: Patch review economics
> Test Suite: Pass this suite before requesting inclusion
> Resubmit Cadence: When to ping the maintainer
> Trusted Reviewers: Help for triaging patches
There is one detail with regards to reviewing process that I'm not sure
how to express. There are some subsystems with co-maintainers, in the
sense that all co-maintainers are equally responsible for the subsystem.
There are other cases where there are sub-maintainers. That's, for example,
the model we use on media. There, we have different sub-maintainers for:
- V4L2 drivers
- Camera Sensors
- Remote Controllers
- HDMI CEC
- DVB
- Media Controller
The usual workflow is that they work as both reviewers and committers.
After they commit a certain amount of patches, they submit for me to
do a final review. This way, most of media patches have at least two
SOBs from non-authors.
On this model, a sub-maintainer is more than a trusted reviewer. Not sure
how to reflect it on this template.
I'll do a better review of the profile when I'll try to write a subsystem
profile for media.
Regards,
Mauro
> Time Zone / Office Hours: When might a maintainer be available
> Checkpatch / Style Cleanups: Policy on pure cleanup patches
> Off-list review: Request for review gates
> TODO: Potential development tasks up for grabs, or active focus areas
>
> The goal of the Subsystem Profile is to set expectations for
> contributors and interim or replacement maintainers for a subsystem.
>
> See Documentation/maintainer/subsystem-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>
> Signed-off-by: Dan Williams <dan.j.williams@intel.com>
> ---
> Documentation/maintainer/index.rst | 1
> Documentation/maintainer/subsystem-profile.rst | 145 ++++++++++++++++++++++++
> MAINTAINERS | 4 +
> 3 files changed, 150 insertions(+)
> create mode 100644 Documentation/maintainer/subsystem-profile.rst
>
> diff --git a/Documentation/maintainer/index.rst b/Documentation/maintainer/index.rst
> index 2a14916930cb..1e6b1aaa6024 100644
> --- a/Documentation/maintainer/index.rst
> +++ b/Documentation/maintainer/index.rst
> @@ -11,4 +11,5 @@ additions to this manual.
>
> configure-git
> pull-requests
> + subsystem-profile
>
> diff --git a/Documentation/maintainer/subsystem-profile.rst b/Documentation/maintainer/subsystem-profile.rst
> new file mode 100644
> index 000000000000..a74b624e0972
> --- /dev/null
> +++ b/Documentation/maintainer/subsystem-profile.rst
> @@ -0,0 +1,145 @@
> +.. _subsystemprofile:
> +
> +Subsystem Profile
> +=================
> +
> +The Subsystem Profile is a collection of policy positions that a
> +maintainer or maintainer team establishes for the their subsystem. While
> +there is a wide range of technical nuance on maintaining disparate
> +sections of the kernel, the Subsystem Profile documents a known set of
> +major process policies that vary between subsystems. What follows is a
> +list of policy questions a maintainer can answer and include a document
> +in the kernel, or on an external website. It advertises to other
> +maintainers and contributors the local policy of the subsystem. Some
> +sections are optional like "Overview", "Off-list review", and "TODO".
> +The others are recommended for all subsystems to address, but no section
> +is mandatory. In addition there are no wrong answers, just document how
> +a subsystem typically operates. Note that the profile follows the
> +subsystem not the maintainer, i.e. there is no expectation that a
> +maintainer of multiple subsystems deploys the same policy across those
> +subsystems.
> +
> +
> +Overview
> +--------
> +In this optional section of the profile provide a free form overview of
> +the subsystem written as a hand-off document. In other words write a
> +note to someone that would receive the “keys to the castle” in the event
> +of extended or unexpected absence. “So, you have recently become the
> +maintainer of the XYZ subsystem, condolences, it is a thankless job,
> +here is the lay of the land.” Details to consider are the extended
> +details that are not included in MAINTAINERS, and not addressed by the
> +other profile questions below. For example details like, who has access
> +to the git tree, branches that are pulled into -next, relevant
> +specifications, issue trackers, and sensitive code areas. If available
> +the Overview should link to other subsystem documentation that may
> +clarify, re-iterate, emphasize / de-emphasize portions of the global
> +process documentation for contributors (CodingStyle, SubmittingPatches,
> +etc...).
> +
> +
> +Core
> +----
> +A list of F: tags (as described by MAINTAINERS) listing what the
> +maintainer considers to be core files. The review and lead time
> +constraints for 'core' code may be stricter given the increased
> +sensitivity and risk of change.
> +
> +
> +Patches or Pull requests
> +------------------------
> +Some subsystems allow contributors to send pull requests, most require
> +mailed patches. State “Patches only”, or “Pull requests accepted”.
> +
> +
> +Last -rc for new feature submissions
> +------------------------------------
> +New feature submissions targeting the next merge window should have
> +their first posting for consideration before this point. Patches that
> +are submitted after this point should be clear that they are targeting
> +the NEXT+1 merge window, or should come with sufficient justification
> +why they should be considered on an expedited schedule. A general
> +guideline is to set expectation with contributors that new feature
> +submissions should appear before -rc5. The answer may be different for
> +'Core:' files, include a second entry prefixed with 'Core:' if so.
> +
> +
> +Last -rc to merge features
> +--------------------------
> +Indicate to contributors the point at which an as yet un-applied patch
> +set will need to wait for the NEXT+1 merge window. Of course there is no
> +obligation to ever except any given patchset, but if the review has not
> +concluded by this point the expectation the contributor should wait and
> +resubmit for the following merge window. The answer may be different for
> +'Core:' files, include a second entry prefixed with 'Core:' if so.
> +
> +
> +Non-author Ack / Review Tags Required
> +-------------------------------------
> +Let contributors and other maintainers know whether they can expect to
> +see the maintainer self-commit patches without 3rd-party review. Some
> +subsystem developer communities are so small as to make this requirement
> +impractical. Others may have been bootstrapped by a submission of
> +self-reviewed code at the outset, but have since moved to a
> +non-author review-required stance. This section sets expectations on the
> +code-review economics in the subsystem. For example, can a contributor
> +trade review of a maintainer's, or other contributor's patches in
> +exchange for consideration of their own.
> +
> +
> +Test Suite
> +----------
> +Indicate the test suite all patches are expected to pass before being
> +submitted for inclusion consideration.
> +
> +
> +Resubmit Cadence
> +----------------
> +Define a rate at which a contributor should wait to resubmit a patchset
> +that has not yet received comments. A general guideline is to try to
> +meet a deadline of 1 - 2 weeks to acknowledge starting consideration for
> +a patch set.
> +
> +
> +Trusted Reviewers
> +-----------------
> +While a maintainer / maintainer-team is expected to be reviewer of last
> +resort the review load is less onerous when distributed amongst
> +contributors and or a trusted set of individuals. This section is
> +distinct from the R: tag (Designated Reviewer). Whereas R: identifies
> +reviewers that should always be copied on a patch submission, the
> +trusted reviewers here are individuals contributors can reach out to if
> +a few 'Resubmit Cadence' intervals have gone by without maintainer
> +action, or to otherwise consult for advice.
> +
> +
> +Time Zone / Office Hours
> +------------------------
> +Let contributors know the time of day when one or more maintainers are
> +usually actively monitoring the mailing list.
> +
> +
> +Checkpatch / Style Cleanups
> +---------------------------
> +For subsystems with long standing code bases it is reasonable to decline
> +to accept pure coding-style fixup patches. This is where you can let
> +contributors know “Standalone style-cleanups are welcome”,
> +“Style-cleanups to existing code only welcome with other feature
> +changes”, or “Standalone style-cleanups to existing code are not
> +welcome”.
> +
> +
> +Off-list review
> +---------------
> +A maintainer may optionally require that contributors seek prior review
> +of patches before initial submission for upstream. For example,
> +“Developers from organization X, please seek internal review before
> +requesting upstream review”. This policy identifies occasions where a
> +maintainer wants to reflect some of the review load back to an
> +organization.
> +
> +
> +TODO
> +----
> +In this optional section include a list of work items that might be
> +suitable for onboarding a new developer to the subsystem.
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 83b7b3943a12..bb4a83a7684d 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -99,6 +99,10 @@ Descriptions of section entries:
> Obsolete: Old code. Something tagged obsolete generally means
> it has been replaced by a better system and you
> should be using that.
> + P: Subsystem Profile document for the maintainer entry. This
> + is either an in-tree file or a URI to a document. The
> + contents of a Subsystem Profile are described in
> + Documentation/maintainer/subsystem-profile.rst.
> F: Files and directories with wildcard patterns.
> A trailing slash includes all files and subdirectory files.
> F: drivers/net/ all files in and below drivers/net
>
> _______________________________________________
> Ksummit-discuss mailing list
> Ksummit-discuss@lists.linuxfoundation.org
> https://lists.linuxfoundation.org/mailman/listinfo/ksummit-discuss
Cheers,
Mauro
next prev parent reply other threads:[~2018-11-15 5:49 UTC|newest]
Thread overview: 61+ messages / expand[flat|nested] mbox.gz Atom feed top
2018-11-15 4:53 [RFC PATCH 0/3] Maintainer Handbook: Subsystem Profile Dan Williams
2018-11-15 4:53 ` [RFC PATCH 1/3] MAINTAINERS: Reclaim the P: tag for " Dan Williams
2018-11-15 5:39 ` [Ksummit-discuss] " Mauro Carvalho Chehab
2018-11-15 20:12 ` Joe Perches
2018-11-15 4:53 ` [RFC PATCH 2/3] MAINTAINERS, Handbook: " Dan Williams
2018-11-15 5:48 ` [Ksummit-discuss] " Julia Lawall
2018-11-15 7:59 ` Geert Uytterhoeven
2018-11-15 13:47 ` Julia Lawall
2018-11-16 12:44 ` Jani Nikula
2018-11-16 17:56 ` Joe Perches
2018-11-17 14:12 ` Rob Herring
2018-11-17 17:03 ` Julia Lawall
2018-11-20 7:28 ` Jani Nikula
2018-11-15 5:49 ` Mauro Carvalho Chehab [this message]
2018-11-15 7:58 ` Geert Uytterhoeven
2018-11-15 8:38 ` Jani Nikula
2018-11-15 18:03 ` Tim.Bird
2018-11-15 23:56 ` Tobin C. Harding
2018-11-15 15:44 ` Mauro Carvalho Chehab
2018-11-16 23:28 ` Randy Dunlap
2018-11-17 11:57 ` Hans Verkuil
2018-11-16 0:11 ` Frank Rowand
2018-11-16 12:04 ` Mauro Carvalho Chehab
2018-11-16 18:57 ` Dan Williams
2018-11-18 12:58 ` Mauro Carvalho Chehab
2018-11-18 17:31 ` Dan Williams
2018-11-18 17:31 ` Dan Williams
2018-11-18 17:34 ` Dan Williams
2018-11-18 17:44 ` Mauro Carvalho Chehab
2018-11-16 16:47 ` Frank Rowand
2018-11-15 4:53 ` [RFC PATCH 3/3] libnvdimm, MAINTAINERS: " Dan Williams
2018-11-15 8:03 ` [Ksummit-discuss] " Geert Uytterhoeven
2018-11-15 14:10 ` Mauro Carvalho Chehab
2018-11-15 16:20 ` Leon Romanovsky
2018-11-15 19:09 ` Mauro Carvalho Chehab
2018-11-15 19:35 ` Leon Romanovsky
2018-11-15 19:40 ` Luck, Tony
2018-11-15 19:43 ` Joe Perches
2018-11-16 11:39 ` Mauro Carvalho Chehab
2018-11-18 7:12 ` Leon Romanovsky
2018-11-16 11:33 ` Mauro Carvalho Chehab
2018-11-16 12:00 ` Jan Kara
2018-11-18 7:00 ` Leon Romanovsky
2018-11-16 20:36 ` Rodrigo Vivi
2018-11-16 23:44 ` Dan Williams
2018-11-17 0:38 ` NeilBrown
2018-11-18 13:11 ` Mauro Carvalho Chehab
2018-11-18 13:03 ` Mauro Carvalho Chehab
2018-11-20 8:10 ` Jani Nikula
2018-11-20 19:31 ` Dan Williams
2018-11-26 11:12 ` Mauro Carvalho Chehab
2018-11-26 15:55 ` Joe Perches
2018-11-16 19:13 ` Dan Williams
2018-11-15 14:30 ` Mauro Carvalho Chehab
2018-11-15 14:51 ` Julia Lawall
2018-11-16 19:20 ` Dan Williams
2018-11-16 2:58 ` y-goto
2018-11-17 0:32 ` [Ksummit-discuss] " David Woodhouse
2018-11-15 5:56 ` [RFC PATCH 0/3] Maintainer Handbook: " Mauro Carvalho Chehab
2018-11-25 10:57 ` Pavel Machek
2018-11-25 20:55 ` Dan Williams
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20181114214922.07d31676@silica.lan \
--to=mchehab@kernel.org \
--cc=dan.j.williams@intel.com \
--cc=dvyukov@google.com \
--cc=gregkh@linuxfoundation.org \
--cc=ksummit-discuss@lists.linuxfoundation.org \
--cc=linux-kernel@vger.kernel.org \
--cc=linux-nvdimm@lists.01.org \
--cc=me@tobin.cc \
--cc=stfrench@microsoft.com \
--cc=vishal.l.verma@intel.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).