maintainer profiles

maintainer profiles

[Randy Dunlap]

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?

-- 
~Randy

Re: maintainer profiles

[Mauro Carvalho Chehab]

On Thu, 9 Apr 2026 17:18:39 -0700
Randy Dunlap <rdunlap@infradead.org> wrote:

> 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?

Heh, from the 5 entries at maintainer-handbooks.rst:

   maintainer-netdev
   maintainer-soc
   maintainer-soc-clean-dts
   maintainer-tip
   maintainer-kvm-x86

we have 3 of them already there at maintainer-entry-profile.rst:

   $ grep process/ Documentation/maintainer/maintainer-entry-profile.rst
   ../process/maintainer-soc
   ../process/maintainer-soc-clean-dts
   ../process/maintainer-netdev

It sounds to me that moving maintainer-tip and maintainer-kvm-x86
to maintainer-entry-profile.rst would be enough to drop
maintainer-handbooks.rst, keeping them consolidated on a single
place.


Thanks,
Mauro

Re: maintainer profiles

[Randy Dunlap]

Hi,

On 4/10/26 1:12 AM, Mauro Carvalho Chehab wrote:
> On Thu, 9 Apr 2026 17:18:39 -0700
> Randy Dunlap <rdunlap@infradead.org> wrote:
> 
>> 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?
> 
> Heh, from the 5 entries at maintainer-handbooks.rst:
> 
>    maintainer-netdev
>    maintainer-soc
>    maintainer-soc-clean-dts
>    maintainer-tip
>    maintainer-kvm-x86
> 
> we have 3 of them already there at maintainer-entry-profile.rst:
> 
>    $ grep process/ Documentation/maintainer/maintainer-entry-profile.rst
>    ../process/maintainer-soc
>    ../process/maintainer-soc-clean-dts
>    ../process/maintainer-netdev
> 
> It sounds to me that moving maintainer-tip and maintainer-kvm-x86
> to maintainer-entry-profile.rst would be enough to drop
> maintainer-handbooks.rst, keeping them consolidated on a single
> place.

Yes, maybe. How about in the other direction:
move them all to maintainer-handbooks.rst?

After all, maintainer-entry-profile.rst says:
  For now, existing maintainer profiles are listed here; we will likely want
  to do something different in the near future.

Also, does anyone know why some of these profiles are numbered and some
are not?  See
  https://docs.kernel.org/maintainer/maintainer-entry-profile.html#existing-profiles
for odd numbering.

thanks.
-- 
~Randy

Re: maintainer profiles

[Randy Dunlap]

On 4/11/26 4:54 PM, Randy Dunlap wrote:
> Hi,
> 
> On 4/10/26 1:12 AM, Mauro Carvalho Chehab wrote:
>> On Thu, 9 Apr 2026 17:18:39 -0700
>> Randy Dunlap <rdunlap@infradead.org> wrote:
>>
>>> 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?
>>
>> Heh, from the 5 entries at maintainer-handbooks.rst:
>>
>>    maintainer-netdev
>>    maintainer-soc
>>    maintainer-soc-clean-dts
>>    maintainer-tip
>>    maintainer-kvm-x86
>>
>> we have 3 of them already there at maintainer-entry-profile.rst:
>>
>>    $ grep process/ Documentation/maintainer/maintainer-entry-profile.rst
>>    ../process/maintainer-soc
>>    ../process/maintainer-soc-clean-dts
>>    ../process/maintainer-netdev
>>
>> It sounds to me that moving maintainer-tip and maintainer-kvm-x86
>> to maintainer-entry-profile.rst would be enough to drop
>> maintainer-handbooks.rst, keeping them consolidated on a single
>> place.
> 
> Yes, maybe. How about in the other direction:
> move them all to maintainer-handbooks.rst?
> 
> After all, maintainer-entry-profile.rst says:
>   For now, existing maintainer profiles are listed here; we will likely want
>   to do something different in the near future.
> 
> Also, does anyone know why some of these profiles are numbered and some
> are not?  See
>   https://docs.kernel.org/maintainer/maintainer-entry-profile.html#existing-profiles
> for odd numbering.

Because they are numbered in their own respective documentation areas...

-- 
~Randy

Re: maintainer profiles

[Mauro Carvalho Chehab]

On Sat, 11 Apr 2026 17:02:56 -0700
Randy Dunlap <rdunlap@infradead.org> wrote:

> On 4/11/26 4:54 PM, Randy Dunlap wrote:
> > Hi,
> > 
> > On 4/10/26 1:12 AM, Mauro Carvalho Chehab wrote:  
> >> On Thu, 9 Apr 2026 17:18:39 -0700
> >> Randy Dunlap <rdunlap@infradead.org> wrote:
> >>  
> >>> 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?  
> >>
> >> Heh, from the 5 entries at maintainer-handbooks.rst:
> >>
> >>    maintainer-netdev
> >>    maintainer-soc
> >>    maintainer-soc-clean-dts
> >>    maintainer-tip
> >>    maintainer-kvm-x86
> >>
> >> we have 3 of them already there at maintainer-entry-profile.rst:
> >>
> >>    $ grep process/ Documentation/maintainer/maintainer-entry-profile.rst
> >>    ../process/maintainer-soc
> >>    ../process/maintainer-soc-clean-dts
> >>    ../process/maintainer-netdev
> >>
> >> It sounds to me that moving maintainer-tip and maintainer-kvm-x86
> >> to maintainer-entry-profile.rst would be enough to drop
> >> maintainer-handbooks.rst, keeping them consolidated on a single
> >> place.  
> > 
> > Yes, maybe. How about in the other direction:
> > move them all to maintainer-handbooks.rst?
> > 
> > After all, maintainer-entry-profile.rst says:
> >   For now, existing maintainer profiles are listed here; we will likely want
> >   to do something different in the near future.

(added Don and Thomas to the thread)

I don't have strong preferences, but the maintainer-entry-profile.rst
contains a "default" maintainership model, so, whatever file name,
I would preserve at least most of its contents somewhere.

Probably a more important discussions is where they should would
sit:

- at Documentation/process;
- at Documentation/maintainer;

Another option would be to move the contents from/two those two
books.

> > 
> > Also, does anyone know why some of these profiles are numbered and some
> > are not?  See
> >   https://docs.kernel.org/maintainer/maintainer-entry-profile.html#existing-profiles
> > for odd numbering.  
> 
> Because they are numbered in their own respective documentation areas...
> 

Yes: they're actually links to other places:

 .. 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

On most cases, the profile is located together with other
subsystem-specific docs, as it makes easier to maintain there,
together with other documents from a given subsystem.

It also saves the need to add extra entries at MAINTAINERS
file.

Thanks,
Mauro

Re: maintainer profiles

[Jonathan Corbet]

Randy Dunlap <rdunlap@infradead.org> 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.

jon

Re: maintainer profiles

[Dan Williams]

Jonathan Corbet wrote:
> Randy Dunlap <rdunlap@infradead.org> 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

Re: maintainer profiles

[Randy Dunlap]

Hi,

On 4/13/26 2:39 PM, Dan Williams wrote:
> Jonathan Corbet wrote:
>> Randy Dunlap <rdunlap@infradead.org> 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

Re: maintainer profiles

[Mauro Carvalho Chehab]

On Mon, 13 Apr 2026 14:39:37 -0700
Dan Williams <djbw@kernel.org> wrote:

> Jonathan Corbet wrote:
> > Randy Dunlap <rdunlap@infradead.org> 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 <mchehab+huawei@kernel.org>

-- 
Thanks,
Mauro

Re: maintainer profiles

[Mauro Carvalho Chehab]

On Tue, 14 Apr 2026 14:37:33 +0200
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:

> On Mon, 13 Apr 2026 14:39:37 -0700
> Dan Williams <djbw@kernel.org> wrote:
> 
> > Jonathan Corbet wrote:  
> > > Randy Dunlap <rdunlap@infradead.org> 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.

It was actually easier than what I would expect ;-)

Just submitted a patch series doing that:

https://lore.kernel.org/linux-doc/cover.1776176108.git.mchehab+huawei@kernel.org/T/#t

> > diff --git a/Documentation/maintainer/maintainer-entry-profile.rst b/Documentation/maintainer/maintainer-entry-profile.rst
> > index 6020d188e13d..58e2af333692 100644

...

If you transform this diff into a patch, it would make sense to
add together with the next version of my RFC ;-)

-- 
Thanks,
Mauro

Re: maintainer profiles

[Dan Williams]

Mauro Carvalho Chehab wrote:
[..] 
> If you transform this diff into a patch, it would make sense to
> add together with the next version of my RFC ;-)

I am ok if you steal whatever you want from it with a Suggested-by.

The bulk of the important work is your maintainers_include.py changes.

Re: maintainer profiles

[Krzysztof Kozlowski]

On 10/04/2026 02:18, Randy Dunlap wrote:
> 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?

Yes, please! Including also the location of actual profiles. I am mostly
looking at them in the sources directly, not web docs, so confusing and
annoying to find them distributed.

Best regards,
Krzysztof

Re: maintainer profiles

[Randy Dunlap]

On 4/14/26 4:18 AM, Krzysztof Kozlowski wrote:
> On 10/04/2026 02:18, Randy Dunlap wrote:
>> 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?
> 
> Yes, please! Including also the location of actual profiles. I am mostly
> looking at them in the sources directly, not web docs, so confusing and
> annoying to find them distributed.

I agree completely but I'm not sure if anyone else does.

-- 
~Randy