Re: [Ksummit-discuss] [RFC PATCH 2/3] MAINTAINERS, Handbook: Subsystem Profile

Cc: linux-doc On Wed, 14 Nov 2018, Dan Williams <dan.j.williams(a)intel.com&gt; wrote: > As presented at the 2018 Linux Plumbers conference [1], the Subsystem > Profile is proposed as a way to reduce friction between committers and > maintainers and perhaps encourage conversations amongst maintainers > about best practice policies. > > The profile contains short answers to some of the common policy > questions a contributor might have, or that a maintainer might consider > formalizing. The current list of maintenance policies is: > > Overview: General introduction to maintaining the subsystem > Core: List of source files considered core > Leaf: List of source files that consume core functionality > Patches or Pull requests: Simple statement of expected submission format > Last -rc for new feature submissions: Expected lead time for submissions > Last -rc to merge features: Deadline for merge decisions > Non-author Ack / Review Tags Required: Patch review economics > Test Suite: Pass this suite before requesting inclusion > Resubmit Cadence: When to ping the maintainer > Trusted Reviewers: Help for triaging patches > Time Zone / Office Hours: When might a maintainer be available > Checkpatch / Style Cleanups: Policy on pure cleanup patches > Off-list review: Request for review gates > TODO: Potential development tasks up for grabs, or active focus areas > > The goal of the Subsystem Profile is to set expectations for > contributors and interim or replacement maintainers for a subsystem. First of all, I welcome documentation efforts like this. The cover letter mainly focuses on the maintainer aspect, and the documentation is added to the maintainer handbook. However, here you set the goal as setting expectations for contributors. The example nvdimm profile in patch 3/3 addresses the reader as a new maintainer, yet goes on to set expectations also for contributors, not just the maintainer. I do think the documentation for contributors and maintainers/committers should be kept separate. Most contributors will never care about the documentation for the latter. We have Documentation/process for contributors, and I think the audience of Documentation/maintainer should be strictly maintainers. In summary, I do think we need all of the documentation you propose, and I appreciate you taking this on, but I think this should be split by audience.