5:03 a.m.
-----Original Message-----
From: Jani Nikula on Thursday, November 15, 2018 12:39 AM
Cc: linux-doc
On Wed, 14 Nov 2018, Dan Williams <dan.j.williams(a)intel.com> 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.
I think there is a spectrum of audiences for this document, including contributors,
reviewers, and maintainers. Some of this information documents the "social
API" between
these groups. So, I think it's handy to have it in one place, viewable by all
parties.
However, designating items that are of special interest to maintainers, or reviewers
or contributors is worthwhile. Maybe having sections in a single document would
serve that purpose?
Put another way, there are pieces of information that are an agreement between
maintainers and contributors, that both should probably be reminded of. Maintaining
such information in 2 places would be a pain, and prone to getting out-of-sync.
Also,
I think over time we want to contributors to feel comfortable becoming reviewers
and maintainers, so it's good for them to learn about the processes that the
maintainers are using. I fear if we kept the information
in role-specific documents, it wouldn't promote this progression.
-- Tim