Thanks for working to improve our documentation!
Naturally, I have some comments, the first of which being to run
scripts/get_maintainer.pl on your patches to get the list of people you
should send them to. Then cut-and-paste it rather then typoing it by
hand :)
Dante Strock <dantestrock@xxxxxxxxxxx> writes:
> From 1fbe3d56d604a0f8a87ed1d3f092b84c2fab4392 Mon Sep 17 00:00:00 2001
> From: Dante Strock <dantestrock@xxxxxxxxxxx>
> Date: Sat, 7 Jun 2025 09:29:36 +0100
> Subject: [PATCH] Documentation/process/: Change 5.x to 6.x; clarify
> terms; added note.
>
> From: Dante Strock <dantestrock@xxxxxxxxxxx>
>
> As a possible suggestion, might it be worthwhile adding a terminology
> section specific to each section of the kernel documentation? That way
> developers have a handy reference to refer back to for terms they might
> not understand.
>
> ---
>
> Documentation/process/2.Process.rst:
>
> - Changed some instances of 5.x to 6.x(though kept some instances of 5.x
> that are used in examples).
> - Clarified the term "rc" in brackets.
> - Added a notice for people installing Git or Mercurial to check their
> distribution repository for the latest version of the software.
>
> Signed-off-by: Dante Strock <dantestrock@xxxxxxxxxxx>
> ---
> Documentation/process/2.Process.rst | 26 +++++++++++++++-----------
> 1 file changed, 15 insertions(+), 11 deletions(-)
This is backward - the changelog goes above the "---" line, any
additional comments go below.
A bulleted list like the above is a good sign that the patch should be
split up - patches should do one thing.
> diff --git a/Documentation/process/2.Process.rst b/Documentation/process/2.Process.rst
> index ef3b116492df..70f8a6603454 100644
> --- a/Documentation/process/2.Process.rst
> +++ b/Documentation/process/2.Process.rst
> @@ -18,17 +18,17 @@ major kernel release happening every two or three months. The recent
> release history looks like this:
>
> ====== =================
> - 5.0 March 3, 2019
> - 5.1 May 5, 2019
> - 5.2 July 7, 2019
> - 5.3 September 15, 2019
> - 5.4 November 24, 2019
> - 5.5 January 6, 2020
> + 6.10 July 14, 2024
> + 6.11 September 15, 2024
> + 6.12 November 17, 2024
> + 6.13 January 20, 2025
> + 6.14 March 24, 2025
> + 6.15 May 25, 2025
> ====== =================
>
> -Every 5.x release is a major kernel release with new features, internal
> +Every 6.x release is a major kernel release with new features, internal
> API changes, and more. A typical release can contain about 13,000
> -changesets with changes to several hundred thousand lines of code. 5.x is
> +changesets with changes to several hundred thousand lines of code. 6.x is
> the leading edge of Linux kernel development; the kernel uses a
> rolling development model which is continually integrating major changes.
I do not object to these change and could apply this, but it might be
nice at some point to rephrase this stuff so that we don't end up doing
these updates repeatedly. After all, we'll be at 7.x within a year...
> @@ -48,9 +48,9 @@ detail later on).
>
> The merge window lasts for approximately two weeks. At the end of this
> time, Linus Torvalds will declare that the window is closed and release the
> -first of the "rc" kernels. For the kernel which is destined to be 5.6,
> +first of the "rc"("release candidate") kernels. For the kernel which is destined to be 6.16,
This is a separate change. But, of course, yesterday's 6.16-rc1 is in
no way a "release candidate". It's really just the naming scheme that
Linus uses for his testing releases, calling them "release candidates"
muddies the water and risks reigniting old debates.
> +Note that not all Linux distributions have the latest version of Git
> +or Mercurial available in their repositories. Consult the package
> +maintainer for your distribution to get the package updated or
> +download it directly from the website.
I almost wonder if the references to Mercurial shouldn't just come out;
I am not aware of anybody using it for kernel work at this point.
I'm also not aware of anybody who has run into trouble because their
distribution lacked a shiny new version of Git. I'm not sure we want to
encourage people to bug their distributors to accelerate updates? Is
this paragraph solving a specific problem that you have encountered?
Thanks,
jon
