Date:   Mon, 23 Jan 2017 14:25:15 +0100
From:   Geert Uytterhoeven <geert@...ux-m68k.org>
To:     Mauro Carvalho Chehab <mchehab@...pensource.com>
Cc:     Joe Perches <joe@...ches.com>, Jonathan Corbet <corbet@....net>,
        "linux-doc@...r.kernel.org" <linux-doc@...r.kernel.org>,
        "linux-kernel@...r.kernel.org" <linux-kernel@...r.kernel.org>
Subject: Re: [PATCH] docs: Make CodingStyle and SubmittingPatches symlinks

Hi Mauro,
On Mon, Jan 23, 2017 at 2:01 PM, Mauro Carvalho Chehab
<mchehab@...pensource.com> wrote:
> Em Mon, 23 Jan 2017 11:44:54 +0100
> Geert Uytterhoeven <geert@...ux-m68k.org> escreveu:
>> On Mon, Jan 23, 2017 at 11:34 AM, Mauro Carvalho Chehab
>> <mchehab@...pensource.com> wrote:
>> > Em Fri, 13 Jan 2017 12:03:24 -0800
>> > Joe Perches <joe@...ches.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@...ches.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.

Sure, but the Internet isn't filled with links pointing newbies to random
old platform-specific source files.

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

Broken links are different from "this file has moved"-style redirections:
they may be found automatically, and chances are higher they may
actually be fixed. Redirections may not be sufficiently annoying to
make people update links pointing to them.

Plus, the redirections are very user-friendly when using a browser:

Example: http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/Documentation/CodingStyle

        This file has moved to process/coding-style.rst

Try http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/process/coding-style.rst

        Path not found

Try http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/Documentation/process/coding-style.rst

        Ah, found it!

Gr{oetje,eeting}s,

                        Geert

--
Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- geert@...ux-m68k.org

In personal conversations with technical people, I call myself a hacker. But
when I'm talking to journalists I just say "programmer" or something like that.
                                -- Linus Torvalds

Powered by blists - more mailing lists