14699c504SDan Williams.. _maintainerentryprofile: 24699c504SDan Williams 34699c504SDan WilliamsMaintainer Entry Profile 44699c504SDan Williams======================== 54699c504SDan Williams 64699c504SDan WilliamsThe Maintainer Entry Profile supplements the top-level process documents 74699c504SDan Williams(submitting-patches, submitting drivers...) with 84699c504SDan Williamssubsystem/device-driver-local customs as well as details about the patch 94699c504SDan Williamssubmission life-cycle. A contributor uses this document to level set 104699c504SDan Williamstheir expectations and avoid common mistakes, maintainers may use these 114699c504SDan Williamsprofiles to look across subsystems for opportunities to converge on 124699c504SDan Williamscommon practices. 134699c504SDan Williams 144699c504SDan Williams 154699c504SDan WilliamsOverview 164699c504SDan Williams-------- 174699c504SDan WilliamsProvide an introduction to how the subsystem operates. While MAINTAINERS 184699c504SDan Williamstells the contributor where to send patches for which files, it does not 194699c504SDan Williamsconvey other subsystem-local infrastructure and mechanisms that aid 204699c504SDan Williamsdevelopment. 210bfa52a4SJonathan Corbet 224699c504SDan WilliamsExample questions to consider: 230bfa52a4SJonathan Corbet 244699c504SDan Williams- Are there notifications when patches are applied to the local tree, or 254699c504SDan Williams merged upstream? 264699c504SDan Williams- Does the subsystem have a patchwork instance? Are patchwork state 274699c504SDan Williams changes notified? 284699c504SDan Williams- Any bots or CI infrastructure that watches the list, or automated 294699c504SDan Williams testing feedback that the subsystem gates acceptance? 304699c504SDan Williams- Git branches that are pulled into -next? 314699c504SDan Williams- What branch should contributors submit against? 324699c504SDan Williams- Links to any other Maintainer Entry Profiles? For example a 334699c504SDan Williams device-driver may point to an entry for its parent subsystem. This makes 344699c504SDan Williams the contributor aware of obligations a maintainer may have have for 354699c504SDan Williams other maintainers in the submission chain. 364699c504SDan Williams 374699c504SDan Williams 384699c504SDan WilliamsSubmit Checklist Addendum 394699c504SDan Williams------------------------- 404699c504SDan WilliamsList mandatory and advisory criteria, beyond the common "submit-checklist", 414699c504SDan Williamsfor a patch to be considered healthy enough for maintainer attention. 424699c504SDan WilliamsFor example: "pass checkpatch.pl with no errors, or warning. Pass the 434699c504SDan Williamsunit test detailed at $URI". 444699c504SDan Williams 454699c504SDan WilliamsThe Submit Checklist Addendum can also include details about the status 464699c504SDan Williamsof related hardware specifications. For example, does the subsystem 474699c504SDan Williamsrequire published specifications at a certain revision before patches 484699c504SDan Williamswill be considered. 494699c504SDan Williams 504699c504SDan Williams 514699c504SDan WilliamsKey Cycle Dates 524699c504SDan Williams--------------- 534699c504SDan WilliamsOne of the common misunderstandings of submitters is that patches can be 544699c504SDan Williamssent at any time before the merge window closes and can still be 554699c504SDan Williamsconsidered for the next -rc1. The reality is that most patches need to 564699c504SDan Williamsbe settled in soaking in linux-next in advance of the merge window 574699c504SDan Williamsopening. Clarify for the submitter the key dates (in terms rc release 584699c504SDan Williamsweek) that patches might considered for merging and when patches need to 594699c504SDan Williamswait for the next -rc. At a minimum: 600bfa52a4SJonathan Corbet 614699c504SDan Williams- Last -rc for new feature submissions: 624699c504SDan Williams New feature submissions targeting the next merge window should have 634699c504SDan Williams their first posting for consideration before this point. Patches that 644699c504SDan Williams are submitted after this point should be clear that they are targeting 654699c504SDan Williams the NEXT+1 merge window, or should come with sufficient justification 664699c504SDan Williams why they should be considered on an expedited schedule. A general 674699c504SDan Williams guideline is to set expectation with contributors that new feature 684699c504SDan Williams submissions should appear before -rc5. 694699c504SDan Williams 704699c504SDan Williams- Last -rc to merge features: Deadline for merge decisions 714699c504SDan Williams Indicate to contributors the point at which an as yet un-applied patch 724699c504SDan Williams set will need to wait for the NEXT+1 merge window. Of course there is no 734699c504SDan Williams obligation to ever except any given patchset, but if the review has not 744699c504SDan Williams concluded by this point the expectation the contributor should wait and 754699c504SDan Williams resubmit for the following merge window. 764699c504SDan Williams 774699c504SDan WilliamsOptional: 780bfa52a4SJonathan Corbet 794699c504SDan Williams- First -rc at which the development baseline branch, listed in the 804699c504SDan Williams overview section, should be considered ready for new submissions. 814699c504SDan Williams 824699c504SDan Williams 834699c504SDan WilliamsReview Cadence 844699c504SDan Williams-------------- 854699c504SDan WilliamsOne of the largest sources of contributor angst is how soon to ping 864699c504SDan Williamsafter a patchset has been posted without receiving any feedback. In 874699c504SDan Williamsaddition to specifying how long to wait before a resubmission this 884699c504SDan Williamssection can also indicate a preferred style of update like, resend the 894699c504SDan Williamsfull series, or privately send a reminder email. This section might also 904699c504SDan Williamslist how review works for this code area and methods to get feedback 914699c504SDan Williamsthat are not directly from the maintainer. 920bfa52a4SJonathan Corbet 930bfa52a4SJonathan CorbetExisting profiles 940bfa52a4SJonathan Corbet----------------- 950bfa52a4SJonathan Corbet 960bfa52a4SJonathan CorbetFor now, existing maintainer profiles are listed here; we will likely want 970bfa52a4SJonathan Corbetto do something different in the near future. 980bfa52a4SJonathan Corbet 990bfa52a4SJonathan Corbet.. toctree:: 1000bfa52a4SJonathan Corbet :maxdepth: 1 1010bfa52a4SJonathan Corbet 10253b7f3aaSJonathan Corbet ../doc-guide/maintainer-profile 1030bfa52a4SJonathan Corbet ../nvdimm/maintainer-entry-profile 104