From patchwork Thu Nov 15 04:53:25 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Dan Williams X-Patchwork-Id: 10683511 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id D63A613BB for ; Thu, 15 Nov 2018 05:05:16 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id C48572BE35 for ; Thu, 15 Nov 2018 05:05:16 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id B83272BE81; Thu, 15 Nov 2018 05:05:16 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-2.9 required=2.0 tests=BAYES_00,MAILING_LIST_MULTI, RCVD_IN_DNSWL_NONE autolearn=ham version=3.3.1 Received: from ml01.01.org (ml01.01.org [198.145.21.10]) (using TLSv1.2 with cipher DHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.wl.linuxfoundation.org (Postfix) with ESMTPS id E86372BE35 for ; Thu, 15 Nov 2018 05:05:15 +0000 (UTC) Received: from [127.0.0.1] (localhost [IPv6:::1]) by ml01.01.org (Postfix) with ESMTP id CDD642119073C; Wed, 14 Nov 2018 21:05:15 -0800 (PST) X-Original-To: linux-nvdimm@lists.01.org Delivered-To: linux-nvdimm@lists.01.org Received-SPF: Pass (sender SPF authorized) identity=mailfrom; client-ip=134.134.136.126; helo=mga18.intel.com; envelope-from=dan.j.williams@intel.com; receiver=linux-nvdimm@lists.01.org Received: from mga18.intel.com (mga18.intel.com [134.134.136.126]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ml01.01.org (Postfix) with ESMTPS id A830121190734 for ; Wed, 14 Nov 2018 21:05:14 -0800 (PST) X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from fmsmga004.fm.intel.com ([10.253.24.48]) by orsmga106.jf.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 14 Nov 2018 21:05:13 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.56,235,1539673200"; d="scan'208";a="106394989" Received: from dwillia2-desk3.jf.intel.com (HELO dwillia2-desk3.amr.corp.intel.com) ([10.54.39.16]) by fmsmga004.fm.intel.com with ESMTP; 14 Nov 2018 21:05:13 -0800 Subject: [RFC PATCH 2/3] MAINTAINERS, Handbook: Subsystem Profile From: Dan Williams To: linux-kernel@vger.kernel.org Date: Wed, 14 Nov 2018 20:53:25 -0800 Message-ID: <154225760492.2499188.14152986544451112930.stgit@dwillia2-desk3.amr.corp.intel.com> In-Reply-To: <154225759358.2499188.15268218778137905050.stgit@dwillia2-desk3.amr.corp.intel.com> References: <154225759358.2499188.15268218778137905050.stgit@dwillia2-desk3.amr.corp.intel.com> User-Agent: StGit/0.18-2-gc94f MIME-Version: 1.0 X-BeenThere: linux-nvdimm@lists.01.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "Linux-nvdimm developer list." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: ksummit-discuss@lists.linuxfoundation.org, corbet@lwn.net, Greg Kroah-Hartman , linux-nvdimm@lists.01.org, Joe Perches , Dmitry Vyukov , Daniel Vetter , Olof Johansson , Thomas Gleixner , Mauro Carvalho Chehab , Linus Torvalds , Steve French , "Tobin C. Harding" Errors-To: linux-nvdimm-bounces@lists.01.org Sender: "Linux-nvdimm" X-Virus-Scanned: ClamAV using ClamSMTP 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 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 Cc: Thomas Gleixner Cc: Mauro Carvalho Chehab Cc: Steve French Cc: Greg Kroah-Hartman Cc: Linus Torvalds Cc: Tobin C. Harding Cc: Olof Johansson Cc: Martin K. Petersen Cc: Daniel Vetter Cc: Joe Perches Cc: Dmitry Vyukov Signed-off-by: Dan Williams Signed-off-by: Mauro Carvalho Chehab --- 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