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 <cor...@lwn.net> Cc: Thomas Gleixner <t...@linutronix.de> Cc: Mauro Carvalho Chehab <mche...@kernel.org> Cc: Steve French <stfre...@microsoft.com> Cc: Greg Kroah-Hartman <gre...@linuxfoundation.org> Cc: Linus Torvalds <torva...@linux-foundation.org> Cc: Tobin C. Harding <m...@tobin.cc> Cc: Olof Johansson <o...@lixom.net> Cc: Martin K. Petersen <martin.peter...@oracle.com> Cc: Daniel Vetter <daniel.vet...@ffwll.ch> Cc: Joe Perches <j...@perches.com> Cc: Dmitry Vyukov <dvyu...@google.com> Cc: Alexandre Belloni <alexandre.bell...@bootlin.com> Signed-off-by: Dan Williams <dan.j.willi...@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 _______________________________________________ Linux-nvdimm mailing list Linux-nvdimm@lists.01.org https://lists.01.org/mailman/listinfo/linux-nvdimm