On Mon, 13 Apr 2026 14:39:37 -0700 Dan Williams <[email protected]> wrote:
> Jonathan Corbet wrote: > > Randy Dunlap <[email protected]> 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. There is already a Python script which parses MAINTAINERS file (Documentation/sphinx/maintainers_include.py). Currently, it expects a Sphinx meta-tag inside Documentation/process/maintainers.rst: .. maintainers-include:: I guess it shouldn't be hard to add support there for a .. maintainers-profile:: Making it creating a set of cross-references is probably easy. Not sure how easy/hard would be to create a TOC tree, though. > 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. Assuming we add such extension, we'll need to sync the P: entries. I'll take a look on trying to extend the Sphinx maintainers extension. > > 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 Sounds good on my eyes. Reviewed-by: Mauro Carvalho Chehab <[email protected]> -- Thanks, Mauro
