Re: [PATCH] MAINTAINERS: adjust to filesystem doc ReST conversion

[Mauro Carvalho Chehab]

Em Wed, 04 Mar 2020 13:24:48 -0800
Joe Perches <joe@xxxxxxxxxxx> escreveu:

> On Wed, 2020-03-04 at 21:28 +0100, Mauro Carvalho Chehab wrote:
> > Em Wed, 4 Mar 2020 13:10:35 -0700
> > Jonathan Corbet <corbet@xxxxxxx> escreveu:
> >   
> > > On Wed,  4 Mar 2020 08:29:50 +0100
> > > Lukas Bulwahn <lukas.bulwahn@xxxxxxxxx> wrote:
> > >   
> > > > Mauro's patch series <cover.1581955849.git.mchehab+huawei@xxxxxxxxxx>
> > > > ("[PATCH 00/44] Manually convert filesystem FS documents to ReST")
> > > > converts many Documentation/filesystems/ files to ReST.
> > > > 
> > > > Since then, ./scripts/get_maintainer.pl --self-test complains with 27
> > > > warnings on Documentation/filesystems/ of this kind:
> > > > 
> > > >   warning: no file matches F: Documentation/filesystems/...
> > > > 
> > > > Adjust MAINTAINERS entries to all files converted from .txt to .rst in the
> > > > patch series and address the 27 warnings.
> > > > 
> > > > Link: https://lore.kernel.org/linux-erofs/cover.1581955849.git.mchehab+huawei@xxxxxxxxxx
> > > > Signed-off-by: Lukas Bulwahn <lukas.bulwahn@xxxxxxxxx>
> > > > ---
> > > > Mauro, please ack.
> > > > Jonathan, pick pick this patch for doc-next.    
> > > 
> > > Sigh, I need to work a MAINTAINERS check into my workflow...
> > > 
> > > Thanks for fixing these, but ... what tree did you generate the patch
> > > against?  I doesn't come close to applying to docs-next.  
> > 
> > I'm starting to suspect that maybe the best workflow would be to just 
> > apply the patches at docs-next keeping links broken, and then run
> > ./scripts/documentation-file-ref-check --fix by the end of a merge
> > window, addressing such breakages.  
> 
> I'm not sure at all that that script will always do the
> right thing with MAINTAINERS,

As it is based on some heuristics, whomever runs it should
double-check the results.

> but it seems to work OK
> except for some renames where a .txt file was directly
> renamed to a .rst file in the same directory where there
> was a similarly named file in a different directory.

Yeah, the script could be smarter to catch this case.

> Likely the direct rename of a filename extension from
> .txt to .rst should always be applied by the script.

Yeah, makes sense to me. Yet, I got one exception for this:
I found somewhere a case were there are both foo.txt and foo.rst,
both with different contents.

The solution I took were to rename foo.txt to bar.txt,
adjusting the cross-references, then convert bar.txt to
bar.rst.

In any case, we're close to finish the conversion. I have
already patches that convert everything to .rst (with a couple of
exceptions), and I took the care of doing the cross-reference fixes 
there. I'm still adjusting some things on this tree. My current plans
are to have them all applied up to Kernel 5.8, and then start looking
on better organizing the docs (I'm already doing that for media docs).

Once all of those patches get merged, .txt -> .rst will
be an exception.

> 
> Anyway, for -next as of today:
> 
> $ git diff --shortstat
>  64 files changed, 116 insertions(+), 116 deletions(-)
> 
> > There are usually lots of churn outside the merge window.
> > 
> > Another alternative would be to split the MAINTAINERS file on a
> > per-subsystem basis. If I remember well, someone proposed this once at
> > LKML. I vaguely remember that there were even a patch (or RFC)
> > adding support for such thing for get_maintainers.pl.  
> 
> Yeah.  get_maintainer.pl does work if the MAINTAINERS
> file is split up a few different ways.
> 
> There was also a tool to do the MAINTAINERS split.
> https://lore.kernel.org/patchwork/patch/817857/
> 
> I doubt that would matter at all given today's tools and
> the general mechanisms of maintainers renaming files and
> not running checkpatch in the first place.

Yeah, it may not produce any concrete results on some parts.
It may help to reduce the conflicts there, though. Also, I guess
some maintainers will take more care, if they start to have
their own */MAINTAINERS files.

Thanks,
Mauro