[PATCH] docs: Update version number from 5.x to 6.x in README.rst

[PATCH] docs: Update version number from 5.x to 6.x in README.rst

[Lukas Bulwahn]

A quick 'grep "5\.x" . -R' on Documentation shows that README.rst,
2.Process.rst and applying-patches.rst all mention the version number "5.x"
for kernel releases.

As the next release will be version 6.0, updating the version number to 6.x
in README.rst seems reasonable.

The description in 2.Process.rst is just a description of recent kernel
releases, it was last updated in the beginning of 2020, and can be
revisited at any time on a regular basis, independent of changing the
version number from 5 to 6. So, there is no need to update this document
now when transitioning from 5.x to 6.x numbering.

The document applying-patches.rst is probably obsolete for most users
anyway, a reader will sufficiently well understand the steps, even it
mentions version 5 rather than version 6. So, do not update that to a
version 6.x numbering scheme.

Update version number from 5.x to 6.x in README.rst only.

Signed-off-by: Lukas Bulwahn <lukas.bulwahn@gmail.com>
---
 Documentation/admin-guide/README.rst | 30 ++++++++++++++--------------
 1 file changed, 15 insertions(+), 15 deletions(-)

diff --git a/Documentation/admin-guide/README.rst b/Documentation/admin-guide/README.rst
index caa3c09a5c3f..9eb6b9042f75 100644
--- a/Documentation/admin-guide/README.rst
+++ b/Documentation/admin-guide/README.rst
@@ -1,9 +1,9 @@
 .. _readme:
 
-Linux kernel release 5.x <http://kernel.org/>
+Linux kernel release 6.x <http://kernel.org/>
 =============================================
 
-These are the release notes for Linux version 5.  Read them carefully,
+These are the release notes for Linux version 6.  Read them carefully,
 as they tell you what this is all about, explain how to install the
 kernel, and what to do if something goes wrong.
 
@@ -63,7 +63,7 @@ Installing the kernel source
    directory where you have permissions (e.g. your home directory) and
    unpack it::
 
-     xz -cd linux-5.x.tar.xz | tar xvf -
+     xz -cd linux-6.x.tar.xz | tar xvf -
 
    Replace "X" with the version number of the latest kernel.
 
@@ -72,12 +72,12 @@ Installing the kernel source
    files.  They should match the library, and not get messed up by
    whatever the kernel-du-jour happens to be.
 
- - You can also upgrade between 5.x releases by patching.  Patches are
+ - You can also upgrade between 6.x releases by patching.  Patches are
    distributed in the xz format.  To install by patching, get all the
    newer patch files, enter the top level directory of the kernel source
-   (linux-5.x) and execute::
+   (linux-6.x) and execute::
 
-     xz -cd ../patch-5.x.xz | patch -p1
+     xz -cd ../patch-6.x.xz | patch -p1
 
    Replace "x" for all versions bigger than the version "x" of your current
    source tree, **in_order**, and you should be ok.  You may want to remove
@@ -85,13 +85,13 @@ Installing the kernel source
    that there are no failed patches (some-file-name# or some-file-name.rej).
    If there are, either you or I have made a mistake.
 
-   Unlike patches for the 5.x kernels, patches for the 5.x.y kernels
+   Unlike patches for the 6.x kernels, patches for the 6.x.y kernels
    (also known as the -stable kernels) are not incremental but instead apply
-   directly to the base 5.x kernel.  For example, if your base kernel is 5.0
-   and you want to apply the 5.0.3 patch, you must not first apply the 5.0.1
-   and 5.0.2 patches. Similarly, if you are running kernel version 5.0.2 and
-   want to jump to 5.0.3, you must first reverse the 5.0.2 patch (that is,
-   patch -R) **before** applying the 5.0.3 patch. You can read more on this in
+   directly to the base 6.x kernel.  For example, if your base kernel is 6.0
+   and you want to apply the 6.0.3 patch, you must not first apply the 6.0.1
+   and 6.0.2 patches. Similarly, if you are running kernel version 6.0.2 and
+   want to jump to 6.0.3, you must first reverse the 6.0.2 patch (that is,
+   patch -R) **before** applying the 6.0.3 patch. You can read more on this in
    :ref:`Documentation/process/applying-patches.rst <applying_patches>`.
 
    Alternatively, the script patch-kernel can be used to automate this
@@ -114,7 +114,7 @@ Installing the kernel source
 Software requirements
 ---------------------
 
-   Compiling and running the 5.x kernels requires up-to-date
+   Compiling and running the 6.x kernels requires up-to-date
    versions of various software packages.  Consult
    :ref:`Documentation/process/changes.rst <changes>` for the minimum version numbers
    required and how to get updates for these packages.  Beware that using
@@ -132,12 +132,12 @@ Build directory for the kernel
    place for the output files (including .config).
    Example::
 
-     kernel source code: /usr/src/linux-5.x
+     kernel source code: /usr/src/linux-6.x
      build directory:    /home/name/build/kernel
 
    To configure and build the kernel, use::
 
-     cd /usr/src/linux-5.x
+     cd /usr/src/linux-6.x
      make O=/home/name/build/kernel menuconfig
      make O=/home/name/build/kernel
      sudo make O=/home/name/build/kernel modules_install install
-- 
2.17.1

Re: [PATCH] docs: Update version number from 5.x to 6.x in README.rst

[Bagas Sanjaya]

On 8/24/22 15:08, Lukas Bulwahn wrote:
> The description in 2.Process.rst is just a description of recent kernel
> releases, it was last updated in the beginning of 2020, and can be
> revisited at any time on a regular basis, independent of changing the
> version number from 5 to 6. So, there is no need to update this document
> now when transitioning from 5.x to 6.x numbering.
> 
The drawback of having quick list of recent kernel releases in 2.Process.rst
is that the list can be quickly outdated with newer releases, unless the list
is updated for every upcoming merge window.

There are two options:

  1. Programmatically generate the list, using last 5 mainline releases
     from Linus's tree, or
  2. Simply point to kernel.org frontpage

CC'ing Tony (since he last updated the list) and Randy Dunlap for suggestion.

Thanks.

-- 
An old man doll... just what I always wanted! - Clara

Re: [PATCH] docs: Update version number from 5.x to 6.x in README.rst

[Randy Dunlap]

On 8/24/22 01:08, Lukas Bulwahn wrote:
> A quick 'grep "5\.x" . -R' on Documentation shows that README.rst,
> 2.Process.rst and applying-patches.rst all mention the version number "5.x"
> for kernel releases.
> 
> As the next release will be version 6.0, updating the version number to 6.x
> in README.rst seems reasonable.
> 
> The description in 2.Process.rst is just a description of recent kernel
> releases, it was last updated in the beginning of 2020, and can be
> revisited at any time on a regular basis, independent of changing the
> version number from 5 to 6. So, there is no need to update this document
> now when transitioning from 5.x to 6.x numbering.
> 
> The document applying-patches.rst is probably obsolete for most users
> anyway, a reader will sufficiently well understand the steps, even it
> mentions version 5 rather than version 6. So, do not update that to a
> version 6.x numbering scheme.

Yeah. And I suspect that scripts/patch-kernel is even more obsolete
than applying-patches.rst.

> Update version number from 5.x to 6.x in README.rst only.
> 
> Signed-off-by: Lukas Bulwahn <lukas.bulwahn@gmail.com>
> ---
>  Documentation/admin-guide/README.rst | 30 ++++++++++++++--------------
>  1 file changed, 15 insertions(+), 15 deletions(-)

Bagas- I don't have a problem with this patch.

If it could be automated easily, that would be OK too.

Or I might add that v6.x patches are located at
https://mirrors.edge.kernel.org/pub/linux/kernel/v6.x/

and v5.x patches are located at
https://mirrors.edge.kernel.org/pub/linux/kernel/v5.x/

thanks.
-- 
~Randy

Re: [PATCH] docs: Update version number from 5.x to 6.x in README.rst

[Lukas Bulwahn]

On Thu, Aug 25, 2022 at 5:08 AM Bagas Sanjaya <bagasdotme@gmail.com> wrote:
>
> On 8/24/22 15:08, Lukas Bulwahn wrote:
> > The description in 2.Process.rst is just a description of recent kernel
> > releases, it was last updated in the beginning of 2020, and can be
> > revisited at any time on a regular basis, independent of changing the
> > version number from 5 to 6. So, there is no need to update this document
> > now when transitioning from 5.x to 6.x numbering.
> >
> The drawback of having quick list of recent kernel releases in 2.Process.rst
> is that the list can be quickly outdated with newer releases, unless the list
> is updated for every upcoming merge window.
>
> There are two options:
>
>   1. Programmatically generate the list, using last 5 mainline releases
>      from Linus's tree, or
>   2. Simply point to kernel.org frontpage
>

As the commit message says, this patch here only touches the README.rst.
The commit message of course also explains why the rest was not
touched, and sure, we can discuss if and how to improve those parts,
but I would like to get an ack on the actual patch first and get that
merged.

So to 2.Process.rst, writing a script to generate the list is
possible, but it is already quite clear that just says "recent", which
is vague anyway. In a software project that is older than 30 years,
"recent" is certainly a bit more relaxed than some other SW project
that just started yesterday.

As it is documentation to convince a new developer, it might be better
to just describe how a new developer can check that the releases are
done very predictable. So, we explain the commands for the reader to
check if he/she/they want to convince themselves.

Lukas

Re: [PATCH] docs: Update version number from 5.x to 6.x in README.rst

[Lukas Bulwahn]

On Thu, Aug 25, 2022 at 5:24 AM Randy Dunlap <rdunlap@infradead.org> wrote:
>
>
>
> On 8/24/22 01:08, Lukas Bulwahn wrote:
> > A quick 'grep "5\.x" . -R' on Documentation shows that README.rst,
> > 2.Process.rst and applying-patches.rst all mention the version number "5.x"
> > for kernel releases.
> >
> > As the next release will be version 6.0, updating the version number to 6.x
> > in README.rst seems reasonable.
> >
> > The description in 2.Process.rst is just a description of recent kernel
> > releases, it was last updated in the beginning of 2020, and can be
> > revisited at any time on a regular basis, independent of changing the
> > version number from 5 to 6. So, there is no need to update this document
> > now when transitioning from 5.x to 6.x numbering.
> >
> > The document applying-patches.rst is probably obsolete for most users
> > anyway, a reader will sufficiently well understand the steps, even it
> > mentions version 5 rather than version 6. So, do not update that to a
> > version 6.x numbering scheme.
>
> Yeah. And I suspect that scripts/patch-kernel is even more obsolete
> than applying-patches.rst.
>

Randy, would you know if there are still users out there?
Would it help to replace this script with a minimal script that only
reports to "Please use git to obtain a recent repository. Update
versions and apply patches with git in a controlled way.".

If someone complains, we revert the patch. If no one complains within
a year or two, we could consider shutting down the infrastructure
creating those patch archives as well, and delete the documentation
referring to that.

Lukas

Re: [PATCH] docs: Update version number from 5.x to 6.x in README.rst

[Randy Dunlap]

On 8/25/22 00:35, Lukas Bulwahn wrote:
> On Thu, Aug 25, 2022 at 5:24 AM Randy Dunlap <rdunlap@infradead.org> wrote:
>>
>>
>>
>> On 8/24/22 01:08, Lukas Bulwahn wrote:
>>> A quick 'grep "5\.x" . -R' on Documentation shows that README.rst,
>>> 2.Process.rst and applying-patches.rst all mention the version number "5.x"
>>> for kernel releases.
>>>
>>> As the next release will be version 6.0, updating the version number to 6.x
>>> in README.rst seems reasonable.
>>>
>>> The description in 2.Process.rst is just a description of recent kernel
>>> releases, it was last updated in the beginning of 2020, and can be
>>> revisited at any time on a regular basis, independent of changing the
>>> version number from 5 to 6. So, there is no need to update this document
>>> now when transitioning from 5.x to 6.x numbering.
>>>
>>> The document applying-patches.rst is probably obsolete for most users
>>> anyway, a reader will sufficiently well understand the steps, even it
>>> mentions version 5 rather than version 6. So, do not update that to a
>>> version 6.x numbering scheme.
>>
>> Yeah. And I suspect that scripts/patch-kernel is even more obsolete
>> than applying-patches.rst.
>>
> 
> Randy, would you know if there are still users out there?
> Would it help to replace this script with a minimal script that only
> reports to "Please use git to obtain a recent repository. Update
> versions and apply patches with git in a controlled way.".

I have no idea, but I haven't seen any comments or references about it
in many years. I think it would be safe to remove it, at least on a
trial basis.


> If someone complains, we revert the patch. If no one complains within
> a year or two, we could consider shutting down the infrastructure
> creating those patch archives as well, and delete the documentation
> referring to that.

Yes, something like that is probably in our future.

-- 
~Randy

Re: [PATCH] docs: Update version number from 5.x to 6.x in README.rst

[Bagas Sanjaya]

On 8/25/22 14:35, Lukas Bulwahn wrote:
> Randy, would you know if there are still users out there?
> Would it help to replace this script with a minimal script that only
> reports to "Please use git to obtain a recent repository. Update
> versions and apply patches with git in a controlled way.".
> 
> If someone complains, we revert the patch. If no one complains within
> a year or two, we could consider shutting down the infrastructure
> creating those patch archives as well, and delete the documentation
> referring to that.

As a refresher: besides Linus's tree (mainline), there is also stable
tree, which is maintained by Greg and Sasha. Most users uses the latter.
So, in case we add warning message to scripts/patch-kernel, we should say
"This script is deprecated; please clone stable tree at [1] with git
instead. If you'd like to apply patches, use git am. If you already have
the tree, use git fetch and git merge to update stable branch of your
choosing."

Thanks.

[1]: https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git

-- 
An old man doll... just what I always wanted! - Clara

Re: [PATCH] docs: Update version number from 5.x to 6.x in README.rst

[Jonathan Corbet]

Lukas Bulwahn <lukas.bulwahn@gmail.com> writes:

> A quick 'grep "5\.x" . -R' on Documentation shows that README.rst,
> 2.Process.rst and applying-patches.rst all mention the version number "5.x"
> for kernel releases.
>
> As the next release will be version 6.0, updating the version number to 6.x
> in README.rst seems reasonable.
>
> The description in 2.Process.rst is just a description of recent kernel
> releases, it was last updated in the beginning of 2020, and can be
> revisited at any time on a regular basis, independent of changing the
> version number from 5 to 6. So, there is no need to update this document
> now when transitioning from 5.x to 6.x numbering.
>
> The document applying-patches.rst is probably obsolete for most users
> anyway, a reader will sufficiently well understand the steps, even it
> mentions version 5 rather than version 6. So, do not update that to a
> version 6.x numbering scheme.
>
> Update version number from 5.x to 6.x in README.rst only.

I've gone ahead and applied this.

For the other files:

 - I don't think 2.Process.rst needs any immediate attention.  We could
   change the wording from "recent release history" to "The release
   history in early 2022 looked like:" or something like that.  There is
   no reason why it has to be the latest releases.

 - applying-patches.rst should just go.  I didn't prevail last time I
   tried to make that point, but I still don't think that we help
   anybody by dragging 1990's instructions around now.

Thanks,

jon

Re: [PATCH] docs: Update version number from 5.x to 6.x in README.rst

[Bagas Sanjaya]

[-- Attachment #1: Type: text/plain, Size: 705 bytes --]

On Thu, Aug 25, 2022 at 12:48:39PM -0600, Jonathan Corbet wrote:
>  - applying-patches.rst should just go.  I didn't prevail last time I
>    tried to make that point, but I still don't think that we help
>    anybody by dragging 1990's instructions around now.
> 

Hi jon,

If we're about to rm applying-patches.rst, at least we also need to add
a warning to the doc, saying "This documentation is obsolete and will be
removed in the future.", while adding the same deprecation message on
scripts/patch-kernel. The script can still be usable and kept around for
a cycle. If no users complain, we will go ahead rm-ing.

Thanks.

-- 
An old man doll... just what I always wanted! - Clara

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH] docs: Update version number from 5.x to 6.x in README.rst

[Randy Dunlap]

Hi--

On 8/25/22 19:19, Bagas Sanjaya wrote:
> On Thu, Aug 25, 2022 at 12:48:39PM -0600, Jonathan Corbet wrote:
>>  - applying-patches.rst should just go.  I didn't prevail last time I
>>    tried to make that point, but I still don't think that we help
>>    anybody by dragging 1990's instructions around now.
>>
> 
> Hi jon,
> 
> If we're about to rm applying-patches.rst, at least we also need to add
> a warning to the doc, saying "This documentation is obsolete and will be
> removed in the future.", while adding the same deprecation message on
> scripts/patch-kernel. The script can still be usable and kept around for
> a cycle. If no users complain, we will go ahead rm-ing.

It already says:

   This document is obsolete.  In most cases, rather than using ``patch``
   manually, you'll almost certainly want to look at using Git instead.

although the bit about "will be removed in the [near] future"
would be a good addition.

-- 
~Randy

Re: [PATCH] docs: Update version number from 5.x to 6.x in README.rst

[Bagas Sanjaya]

On 8/26/22 01:48, Jonathan Corbet wrote:
>  - applying-patches.rst should just go.  I didn't prevail last time I
>    tried to make that point, but I still don't think that we help
>    anybody by dragging 1990's instructions around now.
> 

Hi jon,

Beside what I say earlier at [1], I also think that we need to have
documentation on how to use git to obtain kernel tree and how to
update the tree, with pointers to external resources for advance
topics on git.

[1]: https://lore.kernel.org/linux-doc/YwgtoiKl5Azt7Pre@debian.me/

Thanks.

-- 
An old man doll... just what I always wanted! - Clara

Re: [PATCH] docs: Update version number from 5.x to 6.x in README.rst

[Jonathan Corbet]

Bagas Sanjaya <bagasdotme@gmail.com> writes:

> On Thu, Aug 25, 2022 at 12:48:39PM -0600, Jonathan Corbet wrote:
>>  - applying-patches.rst should just go.  I didn't prevail last time I
>>    tried to make that point, but I still don't think that we help
>>    anybody by dragging 1990's instructions around now.
>> 
>
> Hi jon,
>
> If we're about to rm applying-patches.rst, at least we also need to add
> a warning to the doc, saying "This documentation is obsolete and will be
> removed in the future.", while adding the same deprecation message on
> scripts/patch-kernel. The script can still be usable and kept around for
> a cycle. If no users complain, we will go ahead rm-ing.

A document isn't an API, it's not like users need time to somehow
migrate away from it.  If people will be affected by the removal of a
document, we probably shouldn't remove it.  The situation here is that
nobody is likely to care.  *Somebody* is probably still updating their
kernel with patches somewhere, but they know what they are doing by now.

A script is different, of course; removing that might actually affect
people.

jon