Commit 22abcd75 authored by Jonathan Corbet's avatar Jonathan Corbet

Merge branch 'maintainer-profile' into docs-next

Patch series from Dan Williams:

At last years Plumbers Conference I proposed the Maintainer Entry
Profile as a document that a maintainer can provide to set contributor
expectations and provide fodder for a discussion between maintainers
about the merits of different maintainer policies.

For those that did not attend, the goal of the Maintainer Entry Profile
is to provide contributors documentation of patch submission
considerations that may vary by subsystem. The session introduction was:

    The first rule of kernel maintenance is that there are no hard and
    fast rules. That state of affairs is both a blessing and a curse. It
    has served the community well to be adaptable to the different
    people and different problem spaces that inhabit the kernel
    community. However, that variability also leads to inconsistent
    experiences for contributors, little to no guidance for new
    contributors, and unnecessary stress on current maintainers.

To be clear, the proposed document does not impose or suggest new rules.
Instead it provides an outlet to document the existing unwritten
policies in effect for a given subsystem.  Over time the hope is that
some of this variability can be up-levelled to new global process
policy, but in the meantime it provides relief for communicating the
guidelines that are being imposed on contributors.

[jc: resolved merge conflicts with the MAINTAINERS file, added a patch
     to fix up various RST issues, and added a TOC section for the
     profiles.]
parents 51e46c7a 0bfa52a4
......@@ -12,4 +12,5 @@ additions to this manual.
configure-git
rebasing-and-merging
pull-requests
maintainer-entry-profile
.. _maintainerentryprofile:
Maintainer Entry Profile
========================
The Maintainer Entry Profile supplements the top-level process documents
(submitting-patches, submitting drivers...) with
subsystem/device-driver-local customs as well as details about the patch
submission life-cycle. 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? Are patchwork state
changes notified?
- Any bots or CI infrastructure that watches the list, or automated
testing feedback that the subsystem gates acceptance?
- 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".
The Submit Checklist Addendum can also include details about the status
of related hardware specifications. For example, does the subsystem
require published specifications at a certain revision before patches
will be considered.
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.
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.
Existing profiles
-----------------
For now, existing maintainer profiles are listed here; we will likely want
to do something different in the near future.
.. toctree::
:maxdepth: 1
../nvdimm/maintainer-entry-profile
LIBNVDIMM Maintainer Entry Profile
==================================
Overview
--------
The libnvdimm subsystem manages persistent memory across multiple
architectures. The mailing list, is tracked by patchwork here:
https://patchwork.kernel.org/project/linux-nvdimm/list/
...and that instance is configured to give feedback to submitters on
patch acceptance and upstream merge. Patches are merged to either the
'libnvdimm-fixes', or 'libnvdimm-for-next' branch. Those branches are
available here:
https://git.kernel.org/pub/scm/linux/kernel/git/nvdimm/nvdimm.git/
In general patches can be submitted against the latest -rc, however if
the incoming code change is dependent on other pending changes then the
patch should be based on the libnvdimm-for-next branch. However, since
persistent memory sits at the intersection of storage and memory there
are cases where patches are more suitable to be merged through a
Filesystem or the Memory Management tree. When in doubt copy the nvdimm
list and the maintainers will help route.
Submissions will be exposed to the kbuild robot for compile regression
testing. It helps to get a success notification from that infrastructure
before submitting, but it is not required.
Submit Checklist Addendum
-------------------------
There are unit tests for the subsystem via the ndctl utility:
https://github.com/pmem/ndctl
Those tests need to be passed before the patches go upstream, but not
necessarily before initial posting. Contact the list if you need help
getting the test environment set up.
### ACPI Device Specific Methods (_DSM)
Before patches enabling for a new _DSM family will be considered it must
be assigned a format-interface-code from the NVDIMM Sub-team of the ACPI
Specification Working Group. In general, the stance of the subsystem is
to push back on the proliferation of NVDIMM command sets, do strongly
consider implementing support for an existing command set. See
drivers/acpi/nfit/nfit.h for the set of support command sets.
Key Cycle Dates
---------------
New submissions can be sent at any time, but if they intend to hit the
next merge window they should be sent before -rc4, and ideally
stabilized in the libnvdimm-for-next branch by -rc6. Of course if a
patch set requires more than 2 weeks of review -rc4 is already too late
and some patches may require multiple development cycles to review.
Review Cadence
--------------
In general, please wait up to one week before pinging for feedback. A
private mail reminder is preferred. Alternatively ask for other
developers that have Reviewed-by tags for libnvdimm changes to take a
look and offer their opinion.
......@@ -102,6 +102,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 wildcard patterns.
A trailing slash includes all files and subdirectory files.
F: drivers/net/ all files in and below drivers/net
......@@ -819,7 +823,7 @@ S: Orphan
F: drivers/usb/gadget/udc/amd5536udc.*
AMD GEODE PROCESSOR/CHIPSET SUPPORT
P: Andres Salomon <dilinger@queued.net>
M: Andres Salomon <dilinger@queued.net>
L: linux-geode@lists.infradead.org (moderated for non-subscribers)
W: http://www.amd.com/us-en/ConnectivitySolutions/TechnicalResources/0,,50_2334_2452_11363,00.html
S: Supported
......@@ -9301,6 +9305,7 @@ M: Dan Williams <dan.j.williams@intel.com>
M: Vishal Verma <vishal.l.verma@intel.com>
M: Dave Jiang <dave.jiang@intel.com>
L: linux-nvdimm@lists.01.org
P: Documentation/nvdimm/maintainer-entry-profile.rst
Q: https://patchwork.kernel.org/project/linux-nvdimm/list/
S: Supported
F: drivers/nvdimm/blk.c
......@@ -9311,6 +9316,7 @@ M: Vishal Verma <vishal.l.verma@intel.com>
M: Dan Williams <dan.j.williams@intel.com>
M: Dave Jiang <dave.jiang@intel.com>
L: linux-nvdimm@lists.01.org
P: Documentation/nvdimm/maintainer-entry-profile.rst
Q: https://patchwork.kernel.org/project/linux-nvdimm/list/
S: Supported
F: drivers/nvdimm/btt*
......@@ -9320,6 +9326,7 @@ M: Dan Williams <dan.j.williams@intel.com>
M: Vishal Verma <vishal.l.verma@intel.com>
M: Dave Jiang <dave.jiang@intel.com>
L: linux-nvdimm@lists.01.org
P: Documentation/nvdimm/maintainer-entry-profile.rst
Q: https://patchwork.kernel.org/project/linux-nvdimm/list/
S: Supported
F: drivers/nvdimm/pmem*
......@@ -9339,6 +9346,7 @@ M: Dave Jiang <dave.jiang@intel.com>
M: Keith Busch <keith.busch@intel.com>
M: Ira Weiny <ira.weiny@intel.com>
L: linux-nvdimm@lists.01.org
P: Documentation/nvdimm/maintainer-entry-profile.rst
Q: https://patchwork.kernel.org/project/linux-nvdimm/list/
T: git git://git.kernel.org/pub/scm/linux/kernel/git/nvdimm/nvdimm.git
S: Supported
......@@ -10204,7 +10212,6 @@ F: drivers/staging/media/tegra-vde/
MEDIA INPUT INFRASTRUCTURE (V4L/DVB)
M: Mauro Carvalho Chehab <mchehab@kernel.org>
P: LinuxTV.org Project
L: linux-media@vger.kernel.org
W: https://linuxtv.org
Q: http://patchwork.kernel.org/project/linux-media/list/
......@@ -13609,7 +13616,6 @@ S: Maintained
F: arch/mips/ralink
RALINK RT2X00 WIRELESS LAN DRIVER
P: rt2x00 project
M: Stanislaw Gruszka <sgruszka@redhat.com>
M: Helmut Schaa <helmut.schaa@googlemail.com>
L: linux-wireless@vger.kernel.org
......@@ -13945,7 +13951,6 @@ S: Supported
F: drivers/net/ethernet/rocker/
ROCKETPORT DRIVER
P: Comtrol Corp.
W: http://www.comtrol.com
S: Maintained
F: Documentation/driver-api/serial/rocket.rst
......@@ -14836,15 +14841,13 @@ F: drivers/video/fbdev/simplefb.c
F: include/linux/platform_data/simplefb.h
SIMTEC EB110ATX (Chalice CATS)
P: Ben Dooks
P: Vincent Sanders <vince@simtec.co.uk>
M: Vincent Sanders <vince@simtec.co.uk>
M: Simtec Linux Team <linux@simtec.co.uk>
W: http://www.simtec.co.uk/products/EB110ATX/
S: Supported
SIMTEC EB2410ITX (BAST)
P: Ben Dooks
P: Vincent Sanders <vince@simtec.co.uk>
M: Vincent Sanders <vince@simtec.co.uk>
M: Simtec Linux Team <linux@simtec.co.uk>
W: http://www.simtec.co.uk/products/EB2410ITX/
S: Supported
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment