diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/maintainer/index.rst | 1 | ||||
| -rw-r--r-- | Documentation/maintainer/maintainer-entry-profile.rst | 102 | ||||
| -rw-r--r-- | Documentation/nvdimm/maintainer-entry-profile.rst | 59 |
3 files changed, 162 insertions, 0 deletions
diff --git a/Documentation/maintainer/index.rst b/Documentation/maintainer/index.rst index 56e2c09dfa39..d904e74e1159 100644 --- a/Documentation/maintainer/index.rst +++ b/Documentation/maintainer/index.rst @@ -12,4 +12,5 @@ additions to this manual. configure-git rebasing-and-merging pull-requests + maintainer-entry-profile diff --git a/Documentation/maintainer/maintainer-entry-profile.rst b/Documentation/maintainer/maintainer-entry-profile.rst new file mode 100644 index 000000000000..3eaddc8ac56d --- /dev/null +++ b/Documentation/maintainer/maintainer-entry-profile.rst @@ -0,0 +1,102 @@ +.. _maintainerentryprofile: + +Maintainer Entry Profile +======================== + +The Maintainer Entry Profile supplements the top-level process documents +(submitting-patches, submitting drivers...) with +subsystem/device-driver-local customs as well as details about the patch +submission life-cycle. A contributor uses this document to level set +their expectations and avoid common mistakes, maintainers may use these +profiles to look across subsystems for opportunities to converge on +common practices. + + +Overview +-------- +Provide an introduction to how the subsystem operates. While MAINTAINERS +tells the contributor where to send patches for which files, it does not +convey other subsystem-local infrastructure and mechanisms that aid +development. + +Example questions to consider: + +- Are there notifications when patches are applied to the local tree, or + merged upstream? +- Does the subsystem have a patchwork instance? Are patchwork state + changes notified? +- Any bots or CI infrastructure that watches the list, or automated + testing feedback that the subsystem gates acceptance? +- Git branches that are pulled into -next? +- What branch should contributors submit against? +- Links to any other Maintainer Entry Profiles? For example a + device-driver may point to an entry for its parent subsystem. This makes + the contributor aware of obligations a maintainer may have have for + other maintainers in the submission chain. + + +Submit Checklist Addendum +------------------------- +List mandatory and advisory criteria, beyond the common "submit-checklist", +for a patch to be considered healthy enough for maintainer attention. +For example: "pass checkpatch.pl with no errors, or warning. Pass the +unit test detailed at $URI". + +The Submit Checklist Addendum can also include details about the status +of related hardware specifications. For example, does the subsystem +require published specifications at a certain revision before patches +will be considered. + + +Key Cycle Dates +--------------- +One of the common misunderstandings of submitters is that patches can be +sent at any time before the merge window closes and can still be +considered for the next -rc1. The reality is that most patches need to +be settled in soaking in linux-next in advance of the merge window +opening. Clarify for the submitter the key dates (in terms rc release +week) that patches might considered for merging and when patches need to +wait for the next -rc. At a minimum: + +- Last -rc for new feature submissions: + New feature submissions targeting the next merge window should have + their first posting for consideration before this point. Patches that + are submitted after this point should be clear that they are targeting + the NEXT+1 merge window, or should come with sufficient justification + why they should be considered on an expedited schedule. A general + guideline is to set expectation with contributors that new feature + submissions should appear before -rc5. + +- Last -rc to merge features: Deadline for merge decisions + Indicate to contributors the point at which an as yet un-applied patch + set will need to wait for the NEXT+1 merge window. Of course there is no + obligation to ever except any given patchset, but if the review has not + concluded by this point the expectation the contributor should wait and + resubmit for the following merge window. + +Optional: + +- First -rc at which the development baseline branch, listed in the + overview section, should be considered ready for new submissions. + + +Review Cadence +-------------- +One of the largest sources of contributor angst is how soon to ping +after a patchset has been posted without receiving any feedback. In +addition to specifying how long to wait before a resubmission this +section can also indicate a preferred style of update like, resend the +full series, or privately send a reminder email. This section might also +list how review works for this code area and methods to get feedback +that are not directly from the maintainer. + +Existing profiles +----------------- + +For now, existing maintainer profiles are listed here; we will likely want +to do something different in the near future. + +.. toctree:: + :maxdepth: 1 + + ../nvdimm/maintainer-entry-profile diff --git a/Documentation/nvdimm/maintainer-entry-profile.rst b/Documentation/nvdimm/maintainer-entry-profile.rst new file mode 100644 index 000000000000..77081fd9be95 --- /dev/null +++ b/Documentation/nvdimm/maintainer-entry-profile.rst @@ -0,0 +1,59 @@ +LIBNVDIMM Maintainer Entry Profile +================================== + +Overview +-------- +The libnvdimm subsystem manages persistent memory across multiple +architectures. The mailing list, is tracked by patchwork here: +https://patchwork.kernel.org/project/linux-nvdimm/list/ +...and that instance is configured to give feedback to submitters on +patch acceptance and upstream merge. Patches are merged to either the +'libnvdimm-fixes', or 'libnvdimm-for-next' branch. Those branches are +available here: +https://git.kernel.org/pub/scm/linux/kernel/git/nvdimm/nvdimm.git/ + +In general patches can be submitted against the latest -rc, however if +the incoming code change is dependent on other pending changes then the +patch should be based on the libnvdimm-for-next branch. However, since +persistent memory sits at the intersection of storage and memory there +are cases where patches are more suitable to be merged through a +Filesystem or the Memory Management tree. When in doubt copy the nvdimm +list and the maintainers will help route. + +Submissions will be exposed to the kbuild robot for compile regression +testing. It helps to get a success notification from that infrastructure +before submitting, but it is not required. + + +Submit Checklist Addendum +------------------------- +There are unit tests for the subsystem via the ndctl utility: +https://github.com/pmem/ndctl +Those tests need to be passed before the patches go upstream, but not +necessarily before initial posting. Contact the list if you need help +getting the test environment set up. + +### ACPI Device Specific Methods (_DSM) +Before patches enabling for a new _DSM family will be considered it must +be assigned a format-interface-code from the NVDIMM Sub-team of the ACPI +Specification Working Group. In general, the stance of the subsystem is +to push back on the proliferation of NVDIMM command sets, do strongly +consider implementing support for an existing command set. See +drivers/acpi/nfit/nfit.h for the set of support command sets. + + +Key Cycle Dates +--------------- +New submissions can be sent at any time, but if they intend to hit the +next merge window they should be sent before -rc4, and ideally +stabilized in the libnvdimm-for-next branch by -rc6. Of course if a +patch set requires more than 2 weeks of review -rc4 is already too late +and some patches may require multiple development cycles to review. + + +Review Cadence +-------------- +In general, please wait up to one week before pinging for feedback. A +private mail reminder is preferred. Alternatively ask for other +developers that have Reviewed-by tags for libnvdimm changes to take a +look and offer their opinion. |