Commit | Line | Data |
---|---|---|
4699c504 DW |
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 | |
e35b5a4c | 10 | their expectations and avoid common mistakes; maintainers may use these |
4699c504 DW |
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. | |
0bfa52a4 | 21 | |
4699c504 | 22 | Example questions to consider: |
0bfa52a4 | 23 | |
4699c504 DW |
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 | |
e35b5a4c | 29 | testing feedback that the subsystem uses to gate acceptance? |
4699c504 DW |
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 | |
2ee26890 | 34 | the contributor aware of obligations a maintainer may have for |
4699c504 DW |
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 | |
e35b5a4c RD |
57 | opening. Clarify for the submitter the key dates (in terms of -rc release |
58 | week) that patches might be considered for merging and when patches need to | |
4699c504 | 59 | wait for the next -rc. At a minimum: |
0bfa52a4 | 60 | |
4699c504 DW |
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 | |
e35b5a4c RD |
73 | obligation to ever accept any given patchset, but if the review has not |
74 | concluded by this point the expectation is the contributor should wait and | |
4699c504 DW |
75 | resubmit for the following merge window. |
76 | ||
77 | Optional: | |
0bfa52a4 | 78 | |
4699c504 DW |
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. | |
0bfa52a4 JC |
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 | ||
53b7f3aa | 102 | ../doc-guide/maintainer-profile |
0bfa52a4 | 103 | ../nvdimm/maintainer-entry-profile |
003ad49f | 104 | ../riscv/patch-acceptance |
86ee6729 | 105 | ../driver-api/media/maintainer-entry-profile |
f621eb13 | 106 | ../driver-api/vfio-pci-device-specific-driver-acceptance |
8ca4fc32 | 107 | ../nvme/feature-and-quirk-policy |