Documentation/maintainer/maintainer-entry-profile.rst

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