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

[Geert Uytterhoeven]

Hi Mauro,

On Mon, Jan 23, 2017 at 11:34 AM, Mauro Carvalho Chehab
<mchehab@xxxxxxxxxxxxxxxx> wrote:
> Em Fri, 13 Jan 2017 12:03:24 -0800
> Joe Perches <joe@xxxxxxxxxxx> 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@xxxxxxxxxxx> 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?
Old (doh) kernels, and new versions of stable kernels will keep on having
them for the next +10 years.

To me, these[*] filenames are more like a user-visible API, 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?

Gr{oetje,eeting}s,

                        Geert

--
Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- geert@xxxxxxxxxxxxxx

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