|
| 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 |
0 commit comments