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

[Kees Cook <keescook@chromium.org>]

On Tue, Sep 17, 2019 at 10:28:17AM -0300, Mauro Carvalho Chehab wrote:
> 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.

That's a good point. I think your other suggestions below address my
"find them all" case...

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

Oh yes, having a .rst of the MAINTAINERS file would be pretty great.
Seems like it could just be a build target (and then dependency) for the
sphinx targets?

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

Whatever the case, please don't let me distract from the actual content
of these profiles: I think it's awesome to capture these details and
makes my life so much easier. :)

-- 
Kees Cook