Ksummit-Discuss Archive on lore.kernel.org
 help / color / Atom feed
From: Dan Williams <dan.j.williams@intel.com>
To: linux-kernel@vger.kernel.org
Cc: 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>,
	Mauro Carvalho Chehab <mchehab@kernel.org>,
	Steve French <stfrench@microsoft.com>,
	"Tobin C. Harding" <me@tobin.cc>
Subject: [Ksummit-discuss] [PATCH v2 2/3] Maintainer Handbook: Maintainer Entry Profile
Date: Wed, 11 Sep 2019 08:48:54 -0700
Message-ID: <156821693396.2951081.7340292149329436920.stgit@dwillia2-desk3.amr.corp.intel.com> (raw)
In-Reply-To: <156821692280.2951081.18036584954940423225.stgit@dwillia2-desk3.amr.corp.intel.com>

As presented at the 2018 Linux Plumbers conference [1], the Maintainer
Entry Profile (formerly Subsystem Profile) is proposed as a way to reduce
friction between committers and maintainers and encourage conversations
amongst maintainers about common best practices. While coding-style,
submit-checklist, and submitting-drivers lay out some common expectations
there remain local customs and maintainer preferences that vary by
subsystem.

The profile contains short answers to some of the common policy questions a
contributor might have that are local to the subsystem / device-driver, or
otherwise not covered by the top-level process documents.

Overview: General introduction to how the subsystem operates
Submit Checklist Addendum: Mechanical items that gate submission staging
Key Cycle Dates:
 - Last -rc for new feature submissions: Expected lead time for submissions
 - Last -rc to merge features: Deadline for merge decisions
Coding Style Addendum: Clarifications of local style preferences
Resubmit Cadence: When to ping the maintainer
Checkpatch / Style Cleanups: Policy on pure cleanup patches

See Documentation/maintainer/maintainer-entry-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>
Cc: Alexandre Belloni <alexandre.belloni@bootlin.com>
Signed-off-by: Dan Williams <dan.j.williams@intel.com>
---
 Documentation/maintainer/index.rst                 |    1 
 .../maintainer/maintainer-entry-profile.rst        |   99 ++++++++++++++++++++
 MAINTAINERS                                        |    4 +
 3 files changed, 104 insertions(+)
 create mode 100644 Documentation/maintainer/maintainer-entry-profile.rst

diff --git a/Documentation/maintainer/index.rst b/Documentation/maintainer/index.rst
index 56e2c09dfa39..d904e74e1159 100644
--- a/Documentation/maintainer/index.rst
+++ b/Documentation/maintainer/index.rst
@@ -12,4 +12,5 @@ additions to this manual.
    configure-git
    rebasing-and-merging
    pull-requests
+   maintainer-entry-profile
 
diff --git a/Documentation/maintainer/maintainer-entry-profile.rst b/Documentation/maintainer/maintainer-entry-profile.rst
new file mode 100644
index 000000000000..aaedf4d6dbf7
--- /dev/null
+++ b/Documentation/maintainer/maintainer-entry-profile.rst
@@ -0,0 +1,99 @@
+.. _maintainerentryprofile:
+
+Maintainer Entry Profile
+========================
+
+The Maintainer Entry Profile supplements the top-level process documents
+(coding-style, submitting-patches...) with subsystem/device-driver-local
+customs as well as details about the patch submission lifecycle. A
+contributor uses this document to level set their expectations and avoid
+common mistakes, maintainers may use these profiles to look across
+subsystems for opportunities to converge on common practices.
+
+
+Overview
+--------
+Provide an introduction to how the subsystem operates. While MAINTAINERS
+tells the contributor where to send patches for which files, it does not
+convey other subsystem-local infrastructure and mechanisms that aid
+development.
+Example questions to consider:
+- Are there notifications when patches are applied to the local tree, or
+  merged upstream?
+- Does the subsystem have a patchwork instance?
+- Any bots or CI infrastructure that watches the list?
+- Git branches that are pulled into -next?
+- What branch should contributors submit against?
+- Links to any other Maintainer Entry Profiles? For example a
+  device-driver may point to an entry for its parent subsystem. This makes
+  the contributor aware of obligations a maintainer may have have for
+  other maintainers in the submission chain.
+
+
+Submit Checklist Addendum
+-------------------------
+List mandatory and advisory criteria, beyond the common "submit-checklist",
+for a patch to be considered healthy enough for maintainer attention.
+For example: "pass checkpatch.pl with no errors, or warning. Pass the
+unit test detailed at $URI".
+
+
+Key Cycle Dates
+---------------
+One of the common misunderstandings of submitters is that patches can be
+sent at any time before the merge window closes and can still be
+considered for the next -rc1. The reality is that most patches need to
+be settled in soaking in linux-next in advance of the merge window
+opening. Clarify for the submitter the key dates (in terms rc release
+week) that patches might considered for merging and when patches need to
+wait for the next -rc. At a minimum:
+- 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.
+
+- Last -rc to merge features: Deadline for merge decisions
+  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.
+
+Optional:
+- First -rc at which the development baseline branch, listed in the
+  overview section, should be considered ready for new submissions.
+
+
+Coding Style Addendum
+---------------------
+While the top-level "coding-style" document covers most style
+considerations there are still discrepancies and local preferences
+across subsystems. If a submitter should be aware of incremental / local
+style guidelines like x-mas tree variable declarations, indentation
+for multi line statements, function definition style, etc., list them
+here.
+
+
+Review Cadence
+--------------
+One of the largest sources of contributor angst is how soon to ping
+after a patchset has been posted without receiving any feedback. In
+addition to specifying how long to wait before a resubmission this
+section can also indicate a preferred style of update like, resend the
+full series, or privately send a reminder email. This section might also
+list how review works for this code area and methods to get feedback
+that are not directly from the maintainer.
+
+
+Style Cleanup Patches
+---------------------
+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".
diff --git a/MAINTAINERS b/MAINTAINERS
index 3f171339df53..e5d111a86e61 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -98,6 +98,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 more details submitting
+	   patches to the given subsystem. This is either an in-tree file,
+	   or a URI. See Documentation/maintainer/maintainer-entry-profile.rst
+	   for details.
 	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

  parent reply index

Thread overview: 82+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2019-09-11 15:48 [Ksummit-discuss] [PATCH v2 0/3] Maintainer Entry Profiles Dan Williams
2019-09-11 15:48 ` [Ksummit-discuss] [PATCH v2 1/3] MAINTAINERS: Reclaim the P: tag for Maintainer Entry Profile Dan Williams
2019-09-13 15:37   ` Mauro Carvalho Chehab
2019-09-11 15:48 ` Dan Williams [this message]
2019-09-16 12:35   ` [Ksummit-discuss] [PATCH v2 2/3] Maintainer Handbook: " Jani Nikula
2019-10-01 13:55   ` Jonathan Corbet
2019-10-01 18:17     ` Martin K. Petersen
2019-11-07 20:13     ` Jonathan Corbet
2019-11-08  2:41       ` Dan Williams
2019-09-11 15:48 ` [Ksummit-discuss] [PATCH v2 3/3] libnvdimm, MAINTAINERS: " Dan Williams
2019-09-11 17:42   ` Vishal Verma
2019-09-11 18:43   ` Dan Carpenter
2019-09-11 22:11     ` Jens Axboe
2019-09-12  7:41       ` Dan Williams
     [not found]         ` <CANiq72k2so3ZcqA3iRziGY=Shd_B1=qGoXXROeAF7Y3+pDmqyA@mail.gmail.com>
2019-09-12 10:18           ` Joe Perches
2019-09-13  7:09       ` Jonathan Corbet
2019-09-13 11:48         ` Dan Carpenter
2019-09-13 12:18           ` Dan Williams
2019-09-13 15:00           ` Randy Dunlap
2019-09-13 15:46             ` Rob Herring
2019-09-13 16:42               ` Joe Perches
2019-09-13 19:32                 ` Rob Herring
2019-09-13 17:57             ` Geert Uytterhoeven
2019-09-16 12:42           ` Jani Nikula
     [not found]           ` <20190917161608.GA12866@ziepe.ca>
2019-09-17 21:59             ` Dan Williams
2019-09-13 21:44       ` Martin K. Petersen
2019-09-16  7:01         ` Dan Carpenter
2019-09-16 17:08           ` Martin K. Petersen
2019-09-16 17:15             ` Mark Brown
2019-09-11 20:30   ` Joe Perches
2019-09-13 16:19   ` [Ksummit-discuss] [PATCH] media: add a subsystem profile documentation Mauro Carvalho Chehab
2019-09-13 16:19     ` Mauro Carvalho Chehab
2019-09-17  3:35     ` [Ksummit-discuss] single maintainer profile directory (was Re: [PATCH] media: add a subsystem profile documentation) Kees Cook
2019-09-17 13:28       ` Mauro Carvalho Chehab
2019-09-17 16:33         ` Kees Cook
2019-09-18 11:23           ` Mauro Carvalho Chehab
2019-09-18 17:39             ` Kees Cook
2019-09-18 18:35               ` Mauro Carvalho Chehab
2019-09-21 19:13             ` Jonathan Corbet
2019-09-21 19:45               ` Mauro Carvalho Chehab
2019-09-23 22:45               ` Kees Cook
2019-09-18 12:36     ` [Ksummit-discuss] [PATCH] media: add a subsystem profile documentation Laurent Pinchart
2019-09-18 13:57       ` Mauro Carvalho Chehab
2019-09-18 17:27         ` Laurent Pinchart
2019-09-18 18:48           ` Mauro Carvalho Chehab
2019-09-19  7:08             ` Dan Carpenter
2019-09-20  5:29               ` Joe Perches
2019-09-20 14:09                 ` Daniel Vetter
2019-09-19  6:56         ` Dan Carpenter
2019-09-19  7:22           ` Geert Uytterhoeven
2019-09-19  8:49             ` Jani Nikula
2019-09-19  8:58               ` Geert Uytterhoeven
2019-09-19  9:52                 ` Jani Nikula
2019-09-20 14:53             ` Laurent Pinchart
2019-09-20 14:59               ` Doug Anderson
2019-09-21  8:56                 ` Jani Nikula
2019-09-23 15:58                   ` Doug Anderson
2019-09-23 16:04                     ` Jonathan Corbet
2019-09-19  9:52           ` Mauro Carvalho Chehab
2019-09-25 17:13           ` Joe Perches
2019-09-25 18:40             ` Kees Cook
2019-09-26 15:14               ` Joe Perches
2019-09-26 15:53                 ` Kees Cook
2019-09-26 16:02                   ` Joe Perches
2019-09-26 16:24                     ` Kees Cook
2019-09-26 10:25             ` Geert Uytterhoeven
2019-09-18 13:59       ` [Ksummit-discuss] [PATCH v2] " Mauro Carvalho Chehab
     [not found]         ` <1e479f17-dbc8-b44d-bd1e-4229a6dbf151@collabora.com>
2019-09-18 14:11           ` Mauro Carvalho Chehab
2019-09-11 16:40 ` [Ksummit-discuss] [PATCH v2 0/3] Maintainer Entry Profiles Martin K. Petersen
2019-09-12 13:31   ` Bart Van Assche
2019-09-12 15:34     ` Joe Perches
2019-09-12 20:01       ` Bart Van Assche
2019-09-12 20:34         ` Joe Perches
2019-09-13 14:26           ` Rob Herring
2019-09-13 18:42             ` Joe Perches
2019-09-13 19:17               ` Mauro Carvalho Chehab
2019-09-13 20:33                 ` Joe Perches
2019-09-13 12:56         ` Matthew Wilcox
2019-09-13 13:54           ` Mauro Carvalho Chehab
2019-09-13 14:59             ` Guenter Roeck
2019-09-13 22:03     ` Martin K. Petersen
2019-09-12 13:10 ` Bart Van Assche

Reply instructions:

You may reply publically 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=156821693396.2951081.7340292149329436920.stgit@dwillia2-desk3.amr.corp.intel.com \
    --to=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=mchehab@kernel.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

Ksummit-Discuss Archive on lore.kernel.org

Archives are clonable:
	git clone --mirror https://lore.kernel.org/ksummit-discuss/0 ksummit-discuss/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 ksummit-discuss ksummit-discuss/ https://lore.kernel.org/ksummit-discuss \
		ksummit-discuss@lists.linuxfoundation.org
	public-inbox-index ksummit-discuss

Example config snippet for mirrors

Newsgroup available over NNTP:
	nntp://nntp.lore.kernel.org/org.linuxfoundation.lists.ksummit-discuss


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git