[PATCH] docs: Make CodingStyle and SubmittingPatches symlinks

[PATCH] docs: Make CodingStyle and SubmittingPatches symlinks

[Joe Perches]

Make these files symlinks to the .rst equivalents

Signed-off-by: Joe Perches <joe@perches.com>
---
 Documentation/CodingStyle       | 2 +-
 Documentation/SubmittingPatches | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)
 mode change 100644 => 120000 Documentation/CodingStyle
 mode change 100644 => 120000 Documentation/SubmittingPatches

diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle
deleted file mode 100644
index 320983ca114e..000000000000
--- a/Documentation/CodingStyle
+++ /dev/null
@@ -1 +0,0 @@
-This file has moved to process/coding-style.rst
diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle
new file mode 120000
index 000000000000..5aacf7ea935a
--- /dev/null
+++ b/Documentation/CodingStyle
@@ -0,0 +1 @@
+./process/coding-style.rst
\ No newline at end of file
diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
deleted file mode 100644
index 81455705e4a6..000000000000
--- a/Documentation/SubmittingPatches
+++ /dev/null
@@ -1 +0,0 @@
-This file has moved to process/submitting-patches.rst
diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
new file mode 120000
index 000000000000..5ca6e8ba3682
--- /dev/null
+++ b/Documentation/SubmittingPatches
@@ -0,0 +1 @@
+./process/submitting-patches.rst
\ No newline at end of file
-- 
2.10.0.rc2.1.g053435c

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

[Jani Nikula]

On Wed, 11 Jan 2017, Joe Perches <joe@perches.com> wrote:
> Make these files symlinks to the .rst equivalents

If we're going to do this (and I really don't mind either way), then
please add

Fixes: 08a9a8d44c1c ("doc: re-add CodingStyle and SubmittingPatches")

and queue to v4.10-rc.

BR,
Jani.

>
> Signed-off-by: Joe Perches <joe@perches.com>
> ---
>  Documentation/CodingStyle       | 2 +-
>  Documentation/SubmittingPatches | 2 +-
>  2 files changed, 2 insertions(+), 2 deletions(-)
>  mode change 100644 => 120000 Documentation/CodingStyle
>  mode change 100644 => 120000 Documentation/SubmittingPatches
>
> diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle
> deleted file mode 100644
> index 320983ca114e..000000000000
> --- a/Documentation/CodingStyle
> +++ /dev/null
> @@ -1 +0,0 @@
> -This file has moved to process/coding-style.rst
> diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle
> new file mode 120000
> index 000000000000..5aacf7ea935a
> --- /dev/null
> +++ b/Documentation/CodingStyle
> @@ -0,0 +1 @@
> +./process/coding-style.rst
> \ No newline at end of file
> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
> deleted file mode 100644
> index 81455705e4a6..000000000000
> --- a/Documentation/SubmittingPatches
> +++ /dev/null
> @@ -1 +0,0 @@
> -This file has moved to process/submitting-patches.rst
> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
> new file mode 120000
> index 000000000000..5ca6e8ba3682
> --- /dev/null
> +++ b/Documentation/SubmittingPatches
> @@ -0,0 +1 @@
> +./process/submitting-patches.rst
> \ No newline at end of file

-- 
Jani Nikula, Intel Open Source Technology Center

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

[Joe Perches]

On Wed, 2017-01-11 at 10:54 +0200, Jani Nikula wrote:
> On Wed, 11 Jan 2017, Joe Perches <joe@perches.com> wrote:
> > Make these files symlinks to the .rst equivalents
> 
> If we're going to do this (and I really don't mind either way), then
> please add
> 
> Fixes: 08a9a8d44c1c ("doc: re-add CodingStyle and SubmittingPatches")

I don't believe this patch "fixes" the other, it just makes it
possible to continue to write "Read Documentation/CodingStyle"
or "Read Documentation/SubmittingPatches" to people that
submit poorly formatted or improper patches.

I attempted to do that a bit ago but then had to write out the
Documentation/process/<foo>.rst equivalents instead.

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

[Jani Nikula]

On Wed, 11 Jan 2017, Joe Perches <joe@perches.com> wrote:
> On Wed, 2017-01-11 at 10:54 +0200, Jani Nikula wrote:
>> On Wed, 11 Jan 2017, Joe Perches <joe@perches.com> wrote:
>> > Make these files symlinks to the .rst equivalents
>> 
>> If we're going to do this (and I really don't mind either way), then
>> please add
>> 
>> Fixes: 08a9a8d44c1c ("doc: re-add CodingStyle and SubmittingPatches")

With this I'm merely saying that wherever 08a9a8d44c1c ends up, this
patch should end up too (if we want symlinks that is). There's enough
confusion with the renames already, I'd like to ensure that v4.10
doesn't end up having one thing, and the future another.

BR,
Jani.

>
> I don't believe this patch "fixes" the other, it just makes it
> possible to continue to write "Read Documentation/CodingStyle"
> or "Read Documentation/SubmittingPatches" to people that
> submit poorly formatted or improper patches.
>
> I attempted to do that a bit ago but then had to write out the
> Documentation/process/<foo>.rst equivalents instead.
>

-- 
Jani Nikula, Intel Open Source Technology Center

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

[Jonathan Corbet]

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?

Thanks,

jon

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

[Joe Perches]

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.

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

[Mauro Carvalho Chehab]

Hi,

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

Sorry to not reply earlier... just returned today from vacations.

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

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.

Thanks,
Mauro

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@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?
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@linux-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

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

[Joe Perches]

On Mon, 2017-01-23 at 11:44 +0100, Geert Uytterhoeven wrote:
> 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.

Yup.

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

[Mauro Carvalho Chehab]

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

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

[Geert Uytterhoeven]

Hi Mauro,
On Mon, Jan 23, 2017 at 2:01 PM, Mauro Carvalho Chehab
<mchehab@s-opensource.com> wrote:
> Em Mon, 23 Jan 2017 11:44:54 +0100
> Geert Uytterhoeven <geert@linux-m68k.org> escreveu:
>> 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.

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@linux-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

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

[Jonathan Corbet]

On Mon, 23 Jan 2017 08:34:58 -0200
Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:

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

So you've all long since forgotten this discussion, I'm sure, but I've
been pondering it on and off for quite a while.

The movement of some of the more well-known documents has been a concern
of mine from the beginning; that is why I delayed those changes for
a cycle and raised the issue at a number of conferences, culminating in
the kernel summit in November.  I got a strong sense of consensus that we
should go ahead and move the files.

As Mauro says, symlinks are forever; they say we'll never really succeed
in rationalizing the structure of Documentation/.  But we don't nail down
the location of any other files in the kernel source tree in this manner,
and my own feeling is that we shouldn't do that here either.  The kernel
source tree is not an API.  So my thinking at the moment is that we should
retain the current "pointer files" in the vague hope that, someday, we
won't need them anymore.

Thanks,

jon

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

[Joe Perches]

(adding Greg KH as I doubt he ever saw the original)

On Tue, 2017-02-14 at 14:34 -0700, Jonathan Corbet wrote:
> On Mon, 23 Jan 2017 08:34:58 -0200
> Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:
> 
> > 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.
> > 
> > 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.
> 
> So you've all long since forgotten this discussion, I'm sure, but I've
> been pondering it on and off for quite a while.
> 
> The movement of some of the more well-known documents has been a concern
> of mine from the beginning; that is why I delayed those changes for
> a cycle and raised the issue at a number of conferences, culminating in
> the kernel summit in November.  I got a strong sense of consensus that we
> should go ahead and move the files.
> 
> As Mauro says, symlinks are forever; they say we'll never really succeed
> in rationalizing the structure of Documentation/.  But we don't nail down
> the location of any other files in the kernel source tree in this manner,
> and my own feeling is that we shouldn't do that here either.  The kernel
> source tree is not an API.  So my thinking at the moment is that we should
> retain the current "pointer files" in the vague hope that, someday, we
> won't need them anymore.

I'm still of the opposite opinion.

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

[Daniel Vetter]

On Tue, Feb 14, 2017 at 02:34:38PM -0700, Jonathan Corbet wrote:
> On Mon, 23 Jan 2017 08:34:58 -0200
> Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:
> 
> > 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.
> > 
> > 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.
> 
> So you've all long since forgotten this discussion, I'm sure, but I've
> been pondering it on and off for quite a while.
> 
> The movement of some of the more well-known documents has been a concern
> of mine from the beginning; that is why I delayed those changes for
> a cycle and raised the issue at a number of conferences, culminating in
> the kernel summit in November.  I got a strong sense of consensus that we
> should go ahead and move the files.
> 
> As Mauro says, symlinks are forever; they say we'll never really succeed
> in rationalizing the structure of Documentation/.  But we don't nail down
> the location of any other files in the kernel source tree in this manner,
> and my own feeling is that we shouldn't do that here either.  The kernel
> source tree is not an API.  So my thinking at the moment is that we should
> retain the current "pointer files" in the vague hope that, someday, we
> won't need them anymore.

It's a tricky balance, but I think your stance is reasonable and seems to
reflect overall consensus (which might chance, we'll see).

+1 from my side.

Thanks, Daniel
-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch