Re: maintainer profiles

[Randy Dunlap]

Hi,

On 4/13/26 2:39 PM, Dan Williams wrote:
> 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.

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