Re: [PATCH] docs: Make CodingStyle and SubmittingPatches symlinks

[Mauro Carvalho Chehab <mchehab@s-opensource.com>]

Em Mon, 23 Jan 2017 11:44:54 +0100
Geert Uytterhoeven <geert@linux-m68k.org> escreveu:

> Hi Mauro,
> 
> On Mon, Jan 23, 2017 at 11:34 AM, Mauro Carvalho Chehab
> <mchehab@s-opensource.com> wrote:
> > Em Fri, 13 Jan 2017 12:03:24 -0800
> > Joe Perches <joe@perches.com> escreveu:  
> >> On Fri, 2017-01-13 at 12:41 -0700, Jonathan Corbet wrote:  
> >> > On Tue, 10 Jan 2017 14:09:51 -0800
> >> > Joe Perches <joe@perches.com> wrote:
> >> >  
> >> > > Make these files symlinks to the .rst equivalents  
> >> >
> >> > So I am not necessarily opposed to doing this, but the changelog lacks
> >> > one important thing: why do we need to make that change?  Have the
> >> > existing one-liner files been a problem somehow?  
> >>
> >> The files tell people to open other files.
> >>
> >> Giving the old link to people just tells them to
> >> use the new filename instead.
> >>
> >> symlinks open the new file automatically.
> >>
> >> $ head Documentation/CodingStyle
> >> This file has moved to process/coding-style.rst
> >>
> >> vs a symlink
> >>
> >> $ head Documentation/CodingStyle
> >> .. _codingstyle:
> >>
> >> Linux kernel coding style
> >> =========================
> >>
> >> This is a short document describing the preferred coding style for the
> >> linux kernel.  Coding style is very personal, and I won't **force** my
> >> views on anybody, but this is what goes for anything that I have to be
> >> able to maintain, and I'd prefer it for most other things too.  Please
> >> at least consider the points made here.  
> >
> > IMHO, we should either use symlinks or files with "replaced by" contents.
> >
> > The main difference between a "pointer file" and a symlink is that the
> > first indicates a temporary solution, teaching people that the
> > file got renamed and were it is located now. As such, we can remove
> > those "pointer files" on some future Kernel releases without much concern.
> >
> > A symlink indicates a more permanent situation, as people will keep
> > using the symlinked files as before. That means that any attempt to
> > remove those in the future will generate concerns.  
> 
> Agreed, about temporary vs. permanent.
> 
> > So, I'm in favor of using the "pointer files" instead, as it
> > gives us an easier way to get rid of them when we find convenient.  
> 
> When will/can we get rid of them?

That's a good question. 

> Old (doh) kernels, and new versions of stable kernels will keep on having
> them for the next +10 years.

Old Kernels used to have a separate directory for x86 32 and 64
bits archs. That didn't prevent us to merge them on an unified x86
architecture.

> To me, these[*] filenames are more like a user-visible API,

Don't agree with it ;) From time to time, we change filenames as
needed.

> which should
> not be changed without given consideration.

> 
> [*] CodingStyle and SubmittingPatches (there may be others) are linked from
>     many web pages and email archives.
>     Anyone looked at how many links Google thinks there are?

I've no idea. I suspect that there won't be that many hiperlinks
pointing to some URL that contains CodingStyle/SubmittingPatches, but I
may be wrong.

It should be said that, due to strong reasons, we broke all URL links to the
Kernel trees in 2011, as the kernel.org git trees were disabled, upstream
moved to github. The upstream tree was also renamed once, also in 2011,
from linux-2.6.git to linux.git (although a symlink still exists).

That helps us to track how many times it takes for people to update
their URLs to keep track to upstream changes.

With that in mind, there are only 4 places using the old URL:

https://www.google.com.br/search?q=http://git.kernel.org/%3Fp%3Dlinux/kernel/git/torvalds/linux-2.6.git%3Ba%3Dblob%3Bf%3DDocumentation/SubmittingPatches&ie=utf-8&oe=utf-8&gws_rd=cr&ei=VvyFWK3wJ4nHwASOmL-IAw#q=%22http:%2F%2Fgit.kernel.org%2F%3Fp%3Dlinux%2Fkernel%2Fgit%2Ftorvalds%2Flinux-2.6.git%22+%22Documentation%2FSubmittingPatches%22

And 6,750 using the new one:

https://www.google.com.br/search?q=https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/Documentation/SubmittingPatches&ie=utf-8&oe=utf-8&gws_rd=cr&ei=Df6FWMmwEoGFwgTRu6PYBQ

So, in 5 years, almost everything got updated. It is hard to tell
when most sites changed it, but I would guess that in 2 years
the relevant places will be pointing already to the proper locations.

Thanks,
Mauro