On Wed, 11 Sep 2019, Dan Williams wrote:
> As presented at the 2018 Linux Plumbers conference [1], the Maintainer
> Entry Profile (formerly Subsystem Profile) is proposed as a way to reduce
> friction between committers and maintainers and encourage conversations
> amongst maintainers about common best practices. While coding-style,
> submit-checklist, and submitting-drivers lay out some common expectations
> there remain local customs and maintainer preferences that vary by
> subsystem.
>
> The profile contains short answers to some of the common policy questions a
> contributor might have that are local to the subsystem / device-driver, or
> otherwise not covered by the top-level process documents.
>
> Overview: General introduction to how the subsystem operates
> Submit Checklist Addendum: Mechanical items that gate submission staging
> Key Cycle Dates:
> - Last -rc for new feature submissions: Expected lead time for submissions
> - Last -rc to merge features: Deadline for merge decisions
> Coding Style Addendum: Clarifications of local style preferences
> Resubmit Cadence: When to ping the maintainer
> Checkpatch / Style Cleanups: Policy on pure cleanup patches
>
> See Documentation/maintainer/maintainer-entry-profile.rst for more details,
> and a follow-on example profile for the libnvdimm subsystem.
>
> [1]: https://linuxplumbersconf.org/event/2/contributions/59/
>
> Cc: Jonathan Corbet
> Cc: Thomas Gleixner
> Cc: Mauro Carvalho Chehab
> Cc: Steve French
> Cc: Greg Kroah-Hartman
> Cc: Linus Torvalds
> Cc: Tobin C. Harding
> Cc: Olof Johansson
> Cc: Martin K. Petersen
> Cc: Daniel Vetter
> Cc: Joe Perches
> Cc: Dmitry Vyukov
> Cc: Alexandre Belloni
> Signed-off-by: Dan Williams
> ---
> Documentation/maintainer/index.rst |1
> .../maintainer/maintainer-entry-profile.rst| 99
>
> MAINTAINERS|4 +
> 3 files changed, 104 insertions(+)
> create mode 100644 Documentation/maintainer/maintainer-entry-profile.rst
>
> 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 ..aaedf4d6dbf7
> --- /dev/null
> +++ b/Documentation/maintainer/maintainer-entry-profile.rst
> @@ -0,0 +1,99 @@
> +.. _maintainerentryprofile:
> +
> +Maintainer Entry Profile
> +
> +
> +The Maintainer Entry Profile supplements the top-level process documents
> +(coding-style, submitting-patches...) with subsystem/device-driver-local
> +customs as well as details about the patch submission lifecycle. 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.
In general I think we're already pretty good at adding and accumulating
documentation, but not so much cleaning up existing and outright
throwing out obsolete documentation.
'wc -l Documentation/process/*' says we already have 11k lines of
generic process documentation.
I would much rather see a streamlined and friendly guide to contributing
to the kernel than more rules, and driver/subsystem specific rules at
that. I would much rather get the feeling from submissions that the long
tail of contributors have actually read and understood the most relevant
parts of Documentation/process.
I'm pretty sure *I* haven't read all of Documentation/process.
My fear is that the entry profiles will only be helpful to the
contributors that already "get it". It may be helpful to the maintainers
in the sense that they can reply to patches with a pointer to the
relevant hoops to jump through.
---
Even so, if this gets merged, I'll probably add something helpful for
drm and/or i915 contributors. But what's the buy-in across the kernel?
If my grep serves me right, there are something like 2000+ entries in
MAINTAINERS. If 10% of them adds a profile, that's a fairly serious
amount of documentation. But can you actually expect more than a handful
of subsystems/drivers to add a profile? Then what's the coverage?
For reference, I've added or promoted adding the B: and C: entries to
MAINTAINERS. Various subsystems and drivers are really picky about where
and how they want bugs reported; in particular some folks only accept
email. Yet networking is the only one to indicate the email preference
in MAINTAINERS. And adding that is a one line change. (There are 19 B:
entries and 7 C: entries in total.)
BR,
Jani.
> +
> +
> +Overview
> +
> +Pr
