Hi, On 4/13/26 2:39 PM, Dan Williams 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. > > 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.
I had not (and have not) checked on the P: entries. However, this patch is close to where I already was, but it (and my patch) causes some problems. (I dropped the duplicate maintainer-soc-clean-dts entry.) E.g., maintainer-handbooks uses :numbered:, but the Media and XFS entries are already numbered, so Sphinx complains about that. I think that numbering isn't needed, so I tried dropping that, but the Media and XFS entries are still numbered, so it looks messy, but that may be OK (better) than 2 mixed lists. I'm not finding a satisfactory answer here (yet). 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 > > -- ~Randy
