0001 .. _maintainerentryprofile:
0002
0003 Maintainer Entry Profile
0004 ========================
0005
0006 The Maintainer Entry Profile supplements the top-level process documents
0007 (submitting-patches, submitting drivers...) with
0008 subsystem/device-driver-local customs as well as details about the patch
0009 submission life-cycle. A contributor uses this document to level set
0010 their expectations and avoid common mistakes; maintainers may use these
0011 profiles to look across subsystems for opportunities to converge on
0012 common practices.
0013
0014
0015 Overview
0016 --------
0017 Provide an introduction to how the subsystem operates. While MAINTAINERS
0018 tells the contributor where to send patches for which files, it does not
0019 convey other subsystem-local infrastructure and mechanisms that aid
0020 development.
0021
0022 Example questions to consider:
0023
0024 - Are there notifications when patches are applied to the local tree, or
0025 merged upstream?
0026 - Does the subsystem have a patchwork instance? Are patchwork state
0027 changes notified?
0028 - Any bots or CI infrastructure that watches the list, or automated
0029 testing feedback that the subsystem uses to gate acceptance?
0030 - Git branches that are pulled into -next?
0031 - What branch should contributors submit against?
0032 - Links to any other Maintainer Entry Profiles? For example a
0033 device-driver may point to an entry for its parent subsystem. This makes
0034 the contributor aware of obligations a maintainer may have for
0035 other maintainers in the submission chain.
0036
0037
0038 Submit Checklist Addendum
0039 -------------------------
0040 List mandatory and advisory criteria, beyond the common "submit-checklist",
0041 for a patch to be considered healthy enough for maintainer attention.
0042 For example: "pass checkpatch.pl with no errors, or warning. Pass the
0043 unit test detailed at $URI".
0044
0045 The Submit Checklist Addendum can also include details about the status
0046 of related hardware specifications. For example, does the subsystem
0047 require published specifications at a certain revision before patches
0048 will be considered.
0049
0050
0051 Key Cycle Dates
0052 ---------------
0053 One of the common misunderstandings of submitters is that patches can be
0054 sent at any time before the merge window closes and can still be
0055 considered for the next -rc1. The reality is that most patches need to
0056 be settled in soaking in linux-next in advance of the merge window
0057 opening. Clarify for the submitter the key dates (in terms of -rc release
0058 week) that patches might be considered for merging and when patches need to
0059 wait for the next -rc. At a minimum:
0060
0061 - Last -rc for new feature submissions:
0062 New feature submissions targeting the next merge window should have
0063 their first posting for consideration before this point. Patches that
0064 are submitted after this point should be clear that they are targeting
0065 the NEXT+1 merge window, or should come with sufficient justification
0066 why they should be considered on an expedited schedule. A general
0067 guideline is to set expectation with contributors that new feature
0068 submissions should appear before -rc5.
0069
0070 - Last -rc to merge features: Deadline for merge decisions
0071 Indicate to contributors the point at which an as yet un-applied patch
0072 set will need to wait for the NEXT+1 merge window. Of course there is no
0073 obligation to ever accept any given patchset, but if the review has not
0074 concluded by this point the expectation is the contributor should wait and
0075 resubmit for the following merge window.
0076
0077 Optional:
0078
0079 - First -rc at which the development baseline branch, listed in the
0080 overview section, should be considered ready for new submissions.
0081
0082
0083 Review Cadence
0084 --------------
0085 One of the largest sources of contributor angst is how soon to ping
0086 after a patchset has been posted without receiving any feedback. In
0087 addition to specifying how long to wait before a resubmission this
0088 section can also indicate a preferred style of update like, resend the
0089 full series, or privately send a reminder email. This section might also
0090 list how review works for this code area and methods to get feedback
0091 that are not directly from the maintainer.
0092
0093 Existing profiles
0094 -----------------
0095
0096 For now, existing maintainer profiles are listed here; we will likely want
0097 to do something different in the near future.
0098
0099 .. toctree::
0100 :maxdepth: 1
0101
0102 ../doc-guide/maintainer-profile
0103 ../nvdimm/maintainer-entry-profile
0104 ../riscv/patch-acceptance
0105 ../driver-api/media/maintainer-entry-profile
0106 ../driver-api/vfio-pci-device-specific-driver-acceptance
