maintainer-entry-profile.rst

  1.. _maintainerentryprofile:
  2
  3Maintainer Entry Profile
  4========================
  5
  6The Maintainer Entry Profile supplements the top-level process documents
  7(submitting-patches, submitting drivers...) with
  8subsystem/device-driver-local customs as well as details about the patch
  9submission life-cycle. A contributor uses this document to level set
 10their expectations and avoid common mistakes; maintainers may use these
 11profiles to look across subsystems for opportunities to converge on
 12common practices.
 13
 14
 15Overview
 16--------
 17Provide an introduction to how the subsystem operates. While MAINTAINERS
 18tells the contributor where to send patches for which files, it does not
 19convey other subsystem-local infrastructure and mechanisms that aid
 20development.
 21
 22Example questions to consider:
 23
 24- Are there notifications when patches are applied to the local tree, or
 25  merged upstream?
 26- Does the subsystem have a patchwork instance? Are patchwork state
 27  changes notified?
 28- Any bots or CI infrastructure that watches the list, or automated
 29  testing feedback that the subsystem uses to gate acceptance?
 30- Git branches that are pulled into -next?
 31- What branch should contributors submit against?
 32- Links to any other Maintainer Entry Profiles? For example a
 33  device-driver may point to an entry for its parent subsystem. This makes
 34  the contributor aware of obligations a maintainer may have for
 35  other maintainers in the submission chain.
 36
 37
 38Submit Checklist Addendum
 39-------------------------
 40List mandatory and advisory criteria, beyond the common "submit-checklist",
 41for a patch to be considered healthy enough for maintainer attention.
 42For example: "pass checkpatch.pl with no errors, or warning. Pass the
 43unit test detailed at $URI".
 44
 45The Submit Checklist Addendum can also include details about the status
 46of related hardware specifications. For example, does the subsystem
 47require published specifications at a certain revision before patches
 48will be considered.
 49
 50
 51Key Cycle Dates
 52---------------
 53One of the common misunderstandings of submitters is that patches can be
 54sent at any time before the merge window closes and can still be
 55considered for the next -rc1. The reality is that most patches need to
 56be settled in soaking in linux-next in advance of the merge window
 57opening. Clarify for the submitter the key dates (in terms of -rc release
 58week) that patches might be considered for merging and when patches need to
 59wait for the next -rc. At a minimum:
 60
 61- Last -rc for new feature submissions:
 62
 63  New feature submissions targeting the next merge window should have
 64  their first posting for consideration before this point. Patches that
 65  are submitted after this point should be clear that they are targeting
 66  the NEXT+1 merge window, or should come with sufficient justification
 67  why they should be considered on an expedited schedule. A general
 68  guideline is to set expectation with contributors that new feature
 69  submissions should appear before -rc5.
 70
 71- Last -rc to merge features: Deadline for merge decisions
 72
 73  Indicate to contributors the point at which an as yet un-applied patch
 74  set will need to wait for the NEXT+1 merge window. Of course there is no
 75  obligation to ever accept any given patchset, but if the review has not
 76  concluded by this point the expectation is the contributor should wait and
 77  resubmit for the following merge window.
 78
 79Optional:
 80
 81- First -rc at which the development baseline branch, listed in the
 82  overview section, should be considered ready for new submissions.
 83
 84
 85Review Cadence
 86--------------
 87One of the largest sources of contributor angst is how soon to ping
 88after a patchset has been posted without receiving any feedback. In
 89addition to specifying how long to wait before a resubmission this
 90section can also indicate a preferred style of update like, resend the
 91full series, or privately send a reminder email. This section might also
 92list how review works for this code area and methods to get feedback
 93that are not directly from the maintainer.
 94
 95Existing profiles
 96-----------------
 97
 98For now, existing maintainer profiles are listed here; we will likely want
 99to do something different in the near future.
100
101.. toctree::
102   :maxdepth: 1
103
104   ../doc-guide/maintainer-profile
105   ../nvdimm/maintainer-entry-profile
106   ../arch/riscv/patch-acceptance
107   ../process/maintainer-soc
108   ../process/maintainer-soc-clean-dts
109   ../driver-api/media/maintainer-entry-profile
110   ../process/maintainer-netdev
111   ../driver-api/vfio-pci-device-specific-driver-acceptance
112   ../nvme/feature-and-quirk-policy
113   ../filesystems/nfs/nfsd-maintainer-entry-profile
114   ../filesystems/xfs/xfs-maintainer-entry-profile
115   ../mm/damon/maintainer-profile