Re: [Ksummit-discuss] single maintainer profile directory (was Re: [PATCH] media: add a subsystem profile documentation)

Mauro Carvalho Chehab
2019-09-17T13:28:27Z

Hi Kees,

Em Mon, 16 Sep 2019 20:35:45 -0700
Kees Cook <keescook@chromium.org> escreveu:

> On Fri, Sep 13, 2019 at 01:19:21PM -0300, Mauro Carvalho Chehab wrote:
> > Document the basic policies of the media subsystem profile.
> >
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> > ---
> >
> > That's basically a modified version of:
> > https://patchwork.linuxtv.org/patch/52999/
> >
> > Applied to the new template
> >
> > Documentation/media/index.rst | 1 +
> > .../media/maintainer-entry-profile.rst | 140 ++++++++++++++++++
>
> One idea I proposed to Dan at the Maintainer's Summit was to collect all
> the profiles is a single directory in Documentation/,

No matter where the profiles will physically be stored, its contents belong
to subsystem-specific documentation, and should be visible at the same index
file as the kAPI docs is located, as anyone interested on submitting patches
for a subsystem should be aware about the subsystem specific policies and
details.

So, my vote is to store them at Documentation/*/<subsystem> (together
with the kAPI book).

> since there are
> two ways someone would want to read profiles:
>
> 1) a single profile, based on a MAINTAINERS entry which includes the path

That is the common case. The problem is that the MAINTAINERS file
currently doesn't generate html output. This is not a problem for
"old school" devs, but a newbie wanting to collaborate to a single
specific subsystem may not notice - or understand - the importance
of the MAINTAINERS file[1].

[1] btw, that's why I submitted a RFC, several years ago, a patch
converting it to ReST - and later - another patch that would be parsing
its contents and producing a ReST output.

That's, by far, the most relevant usecase for the profiles, as the
audience is the ~4k Kernel developers.

> 2) all of them, to study for various reasons

I suspect that only core people will have interest on study them.

Those people are more skilled, and can easily find all those files with
a simple grep:

$ grep "^P:\s" MAINTAINERS|cut -d':' -f2-

or

$ git grep "^P:\s" MAINTAINERS|cut -d: -f3-

If, for whatever reason, he would prefer an HTML output [1], he could even
create an index file with all of those with something like:

$ for i in $(grep "^P:\s" MAINTAINERS|cut -d':' -f2-); do j=${i/rst/html}; echo "$j "; done >Documentation/output/index_profiles.html

We might, instead, teach the Documentation/Makefile to create something
like the above, but, IMHO, that would just add more complexity to the
build without a good reason.

[1] I doubt that core devs would prefer seeing this in html form, but some
variant of the above could be used, for example, to create symlinks for
all profile docs into a "study" directory.

> The #2 case is helped by having them all in one directory with a single
> index.rst, etc. Then similar profiles are able to merge, etc.

Thanks,
Mauro