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

[Mauro Carvalho Chehab <mchehab+samsung@kernel.org>]

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 "<a href=\"$j\">$j</a><br/>"; 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