Re: maintainer profiles

[Dan Williams]

Jonathan Corbet wrote:
> Randy Dunlap <rdunlap@xxxxxxxxxxxxx> writes:
> 
> > Hi,
> >
> > Is there supposed to be a difference (or distinction) in the contents of
> >
> > Documentation/process/maintainer-handbooks.rst
> > and
> > Documentation/maintainer/maintainer-entry-profile.rst
> > ?
> >
> > Can they be combined into one location?
> 
> Late to the party, sorry ... the original idea, I believe, was that
> maintainer-handbooks.rst would be for developers looking for a guidebook
> for a specific subsystem, while maintainer-entry-profile.rst was about
> how maintainers themselves should write their subsystem guide.
> Doubtless things have drifted since then...  But the intended audiences
> were different, so it might be good to think about bringing them back
> into focus.

Right, I think something (roughly / hand-wavy) like the below is the
intent. However, as I write that I notice that the combined list is a
bit of a mess. I also notice that there are more "P:" entries in
MAINTAINERS than there are entries in this maintainer-handbooks.rst
list.

So this probably wants to be a script that can build Documentation links
from MAINTAINERS, or otherwise provide a script for developers to query
a kernel tree for additional submission guides. It is probably not as
important for the built docs to link all guides as it is for developers
(or their agents) to live query a tree they are developing against.

Note the problem goes both ways, there are P: entries not in the
combined handbook list, like the Security subsystem, and there are
handbook entries without a P:, like the Tip tree.

diff --git a/Documentation/maintainer/maintainer-entry-profile.rst b/Documentation/maintainer/maintainer-entry-profile.rst
index 6020d188e13d..58e2af333692 100644
--- a/Documentation/maintainer/maintainer-entry-profile.rst
+++ b/Documentation/maintainer/maintainer-entry-profile.rst
@@ -92,24 +92,8 @@ 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
-
-   ../doc-guide/maintainer-profile
-   ../nvdimm/maintainer-entry-profile
-   ../arch/riscv/patch-acceptance
-   ../process/maintainer-soc
-   ../process/maintainer-soc-clean-dts
-   ../driver-api/media/maintainer-entry-profile
-   ../process/maintainer-netdev
-   ../driver-api/vfio-pci-device-specific-driver-acceptance
-   ../nvme/feature-and-quirk-policy
-   ../filesystems/nfs/nfsd-maintainer-entry-profile
-   ../filesystems/xfs/xfs-maintainer-entry-profile
-   ../mm/damon/maintainer-profile
+Maintainer Handbooks
+--------------------
+
+For examples of other subsystem handbooks see
+Documentation/process/maintainer-handbooks.rst.
diff --git a/Documentation/process/maintainer-handbooks.rst b/Documentation/process/maintainer-handbooks.rst
index 976391cec528..bc9299a04b1f 100644
--- a/Documentation/process/maintainer-handbooks.rst
+++ b/Documentation/process/maintainer-handbooks.rst
@@ -9,14 +9,33 @@ The purpose of this document is to provide subsystem specific information
 which is supplementary to the general development process handbook
 :ref:`Documentation/process <development_process_main>`.
 
+For developers, see below for all the known subsystem specific guides.
+If the subsystem you are contributing to does not have a guide listed
+here, it is fair to seek clarification of questions raised in
+Documentation/maintainer/maintainer-entry-profile.rst.
+
+For maintainers, consider documenting additional requirements and
+expectations if submissions routinely overlook specific submission
+criteria. See Documentation/maintainer/maintainer-entry-profile.rst.
+
 Contents:
 
 .. toctree::
    :numbered:
    :maxdepth: 2
 
+   maintainer-kvm-x86
    maintainer-netdev
    maintainer-soc
    maintainer-soc-clean-dts
+   maintainer-soc-clean-dts
    maintainer-tip
-   maintainer-kvm-x86
+   ../arch/riscv/patch-acceptance
+   ../doc-guide/maintainer-profile
+   ../driver-api/media/maintainer-entry-profile
+   ../driver-api/vfio-pci-device-specific-driver-acceptance
+   ../filesystems/nfs/nfsd-maintainer-entry-profile
+   ../filesystems/xfs/xfs-maintainer-entry-profile
+   ../mm/damon/maintainer-profile
+   ../nvdimm/maintainer-entry-profile
+   ../nvme/feature-and-quirk-policy