[PATCH 0/2] docs: *-regressions.rst: Tweaks to the commands

[PATCH 0/2] docs: *-regressions.rst: Tweaks to the commands

[Nícolas F. R. A. Prado]

A couple tweaks to the commands in the regression documentation to make
them up-to-date and less confusing.

Signed-off-by: Nícolas F. R. A. Prado <nfraprado@collabora.com>
---
Nícolas F. R. A. Prado (2):
      docs: *-regressions.rst: Use collon after regzbot introduced command
      docs: handling-regressions.rst: Update regzbot command fixed-by to fix

 Documentation/admin-guide/reporting-regressions.rst |  2 +-
 Documentation/process/handling-regressions.rst      | 12 ++++++------
 2 files changed, 7 insertions(+), 7 deletions(-)
---
base-commit: 11afac187274a6177a7ac82997f8691c0f469e41
change-id: 20240308-regzbot-fixes-43a28fd4b621

Best regards,
-- 
Nícolas F. R. A. Prado <nfraprado@collabora.com>

[PATCH 1/2] docs: *-regressions.rst: Use collon after regzbot introduced command

[Nícolas F. R. A. Prado]

All the examples in the reference documentation for regzbot have a
collon after the "introduced" command, while on the kernel documentation
some have and others don't. This suggests both are acceptable, but in
order to avoid confusion, add collons after all the commands to match
the reference docs.

Link: https://gitlab.com/knurd42/regzbot/-/blob/main/docs/reference.md
Signed-off-by: Nícolas F. R. A. Prado <nfraprado@collabora.com>
---
 Documentation/admin-guide/reporting-regressions.rst |  2 +-
 Documentation/process/handling-regressions.rst      | 10 +++++-----
 2 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/Documentation/admin-guide/reporting-regressions.rst b/Documentation/admin-guide/reporting-regressions.rst
index d8adccdae23f..76b246ecf21b 100644
--- a/Documentation/admin-guide/reporting-regressions.rst
+++ b/Documentation/admin-guide/reporting-regressions.rst
@@ -31,7 +31,7 @@ The important bits (aka "TL;DR")
    Linux kernel regression tracking bot "regzbot" track the issue by specifying
    when the regression started like this::
 
-       #regzbot introduced v5.13..v5.14-rc1
+       #regzbot introduced: v5.13..v5.14-rc1
 
 
 All the details on Linux kernel regressions relevant for users
diff --git a/Documentation/process/handling-regressions.rst b/Documentation/process/handling-regressions.rst
index 5d3c3de3f4ec..42b13f77b019 100644
--- a/Documentation/process/handling-regressions.rst
+++ b/Documentation/process/handling-regressions.rst
@@ -27,11 +27,11 @@ The important bits (aka "The TL;DR")
    is optional, but recommended):
 
     * For mailed reports, check if the reporter included a line like ``#regzbot
-      introduced v5.13..v5.14-rc1``. If not, send a reply (with the regressions
+      introduced: v5.13..v5.14-rc1``. If not, send a reply (with the regressions
       list in CC) containing a paragraph like the following, which tells regzbot
       when the issue started to happen::
 
-       #regzbot ^introduced 1f2e3d4c5b6a
+       #regzbot ^introduced: 1f2e3d4c5b6a
 
     * When forwarding reports from a bug tracker to the regressions list (see
       above), include a paragraph like the following::
@@ -79,7 +79,7 @@ When doing either, consider making the Linux kernel regression tracking bot
 "regzbot" immediately start tracking the issue:
 
  * For mailed reports, check if the reporter included a "regzbot command" like
-   ``#regzbot introduced 1f2e3d4c5b6a``. If not, send a reply (with the
+   ``#regzbot introduced: 1f2e3d4c5b6a``. If not, send a reply (with the
    regressions list in CC) with a paragraph like the following:::
 
        #regzbot ^introduced: v5.13..v5.14-rc1
@@ -398,9 +398,9 @@ By using a 'regzbot command' in a direct or indirect reply to the mail with the
 regression report. These commands need to be in their own paragraph (IOW: they
 need to be separated from the rest of the mail using blank lines).
 
-One such command is ``#regzbot introduced <version or commit>``, which makes
+One such command is ``#regzbot introduced: <version or commit>``, which makes
 regzbot consider your mail as a regressions report added to the tracking, as
-already described above; ``#regzbot ^introduced <version or commit>`` is another
+already described above; ``#regzbot ^introduced: <version or commit>`` is another
 such command, which makes regzbot consider the parent mail as a report for a
 regression which it starts to track.
 

-- 
2.44.0

[PATCH 2/2] docs: handling-regressions.rst: Update regzbot command fixed-by to fix

[Nícolas F. R. A. Prado]

On the reference documentation for regzbot, the fixed-by command has
been renamed to fix. Update the kernel documentation accordingly.

Link: https://gitlab.com/knurd42/regzbot/-/blob/main/docs/reference.md
Link: https://gitlab.com/knurd42/regzbot/-/commit/6d8d30f6bda84e1b711121bb98a07a464d3f089a
Signed-off-by: Nícolas F. R. A. Prado <nfraprado@collabora.com>
---
 Documentation/process/handling-regressions.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/process/handling-regressions.rst b/Documentation/process/handling-regressions.rst
index 42b13f77b019..ce6753a674f3 100644
--- a/Documentation/process/handling-regressions.rst
+++ b/Documentation/process/handling-regressions.rst
@@ -432,7 +432,7 @@ or itself is a reply to that mail:
  * Mark a regression as fixed by a commit that is heading upstream or already
    landed::
 
-       #regzbot fixed-by: 1f2e3d4c5d
+       #regzbot fix: 1f2e3d4c5d
 
  * Mark a regression as a duplicate of another one already tracked by regzbot::
 

-- 
2.44.0

Re: [PATCH 1/2] docs: *-regressions.rst: Use collon after regzbot introduced command

[Thorsten Leemhuis]

Thx for this!

On 08.03.24 15:09, Nícolas F. R. A. Prado wrote:
> All the examples in the reference documentation for regzbot have a
> collon

s/collon/colon/ here and a few lines below as well. And in the subject
as well. Speaking of which: something like "docs: *-regressions.rst:
add colon to regzbot commands" might be better.

> after the "introduced" command, while on the kernel documentation
> some have and others don't. This suggests both are acceptable,

Yup.

> but in
> order to avoid confusion, add collons after all the commands to match
> the reference docs.

Yeah, good idea. I likely would have done this myself soon while doing a
few other changes I plan, but whatever. :-D

> Link: https://gitlab.com/knurd42/regzbot/-/blob/main/docs/reference.md
> Signed-off-by: Nícolas F. R. A. Prado <nfraprado@collabora.com>

With the changes above:

Reviewed-by: Thorsten Leemhuis <linux@leemhuis.info>

Side note: I wonder if the commit message could come a bit quicker to
the point (something along the lines of "Use colons as command
terminator everywhere for consistency, even if it not strictly
necessary. That way it will also match regzbot's reference
documentation.". But not really important I guess. Up to John.

Ciao, Thorsten

> ---
>  Documentation/admin-guide/reporting-regressions.rst |  2 +-
>  Documentation/process/handling-regressions.rst      | 10 +++++-----
>  2 files changed, 6 insertions(+), 6 deletions(-)
> 
> diff --git a/Documentation/admin-guide/reporting-regressions.rst b/Documentation/admin-guide/reporting-regressions.rst
> index d8adccdae23f..76b246ecf21b 100644
> --- a/Documentation/admin-guide/reporting-regressions.rst
> +++ b/Documentation/admin-guide/reporting-regressions.rst
> @@ -31,7 +31,7 @@ The important bits (aka "TL;DR")
>     Linux kernel regression tracking bot "regzbot" track the issue by specifying
>     when the regression started like this::
>  
> -       #regzbot introduced v5.13..v5.14-rc1
> +       #regzbot introduced: v5.13..v5.14-rc1
>  
>  
>  All the details on Linux kernel regressions relevant for users
> diff --git a/Documentation/process/handling-regressions.rst b/Documentation/process/handling-regressions.rst
> index 5d3c3de3f4ec..42b13f77b019 100644
> --- a/Documentation/process/handling-regressions.rst
> +++ b/Documentation/process/handling-regressions.rst
> @@ -27,11 +27,11 @@ The important bits (aka "The TL;DR")
>     is optional, but recommended):
>  
>      * For mailed reports, check if the reporter included a line like ``#regzbot
> -      introduced v5.13..v5.14-rc1``. If not, send a reply (with the regressions
> +      introduced: v5.13..v5.14-rc1``. If not, send a reply (with the regressions
>        list in CC) containing a paragraph like the following, which tells regzbot
>        when the issue started to happen::
>  
> -       #regzbot ^introduced 1f2e3d4c5b6a
> +       #regzbot ^introduced: 1f2e3d4c5b6a
>  
>      * When forwarding reports from a bug tracker to the regressions list (see
>        above), include a paragraph like the following::
> @@ -79,7 +79,7 @@ When doing either, consider making the Linux kernel regression tracking bot
>  "regzbot" immediately start tracking the issue:
>  
>   * For mailed reports, check if the reporter included a "regzbot command" like
> -   ``#regzbot introduced 1f2e3d4c5b6a``. If not, send a reply (with the
> +   ``#regzbot introduced: 1f2e3d4c5b6a``. If not, send a reply (with the
>     regressions list in CC) with a paragraph like the following:::
>  
>         #regzbot ^introduced: v5.13..v5.14-rc1
> @@ -398,9 +398,9 @@ By using a 'regzbot command' in a direct or indirect reply to the mail with the
>  regression report. These commands need to be in their own paragraph (IOW: they
>  need to be separated from the rest of the mail using blank lines).
>  
> -One such command is ``#regzbot introduced <version or commit>``, which makes
> +One such command is ``#regzbot introduced: <version or commit>``, which makes
>  regzbot consider your mail as a regressions report added to the tracking, as
> -already described above; ``#regzbot ^introduced <version or commit>`` is another
> +already described above; ``#regzbot ^introduced: <version or commit>`` is another
>  such command, which makes regzbot consider the parent mail as a report for a
>  regression which it starts to track.
>  
> 

Re: [PATCH 2/2] docs: handling-regressions.rst: Update regzbot command fixed-by to fix

[Thorsten Leemhuis]

Thx for this!

On 08.03.24 15:10, Nícolas F. R. A. Prado wrote:
> On the reference documentation for regzbot, the fixed-by command has
> been renamed to fix. Update the kernel documentation accordingly.
> 
> Link: https://gitlab.com/knurd42/regzbot/-/blob/main/docs/reference.md
> Link: https://gitlab.com/knurd42/regzbot/-/commit/6d8d30f6bda84e1b711121bb98a07a464d3f089a
> Signed-off-by: Nícolas F. R. A. Prado <nfraprado@collabora.com>

Reviewed-by: Thorsten Leemhuis <linux@leemhuis.info>

> ---
>  Documentation/process/handling-regressions.rst | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/Documentation/process/handling-regressions.rst b/Documentation/process/handling-regressions.rst
> index 42b13f77b019..ce6753a674f3 100644
> --- a/Documentation/process/handling-regressions.rst
> +++ b/Documentation/process/handling-regressions.rst
> @@ -432,7 +432,7 @@ or itself is a reply to that mail:
>   * Mark a regression as fixed by a commit that is heading upstream or already
>     landed::
>  
> -       #regzbot fixed-by: 1f2e3d4c5d
> +       #regzbot fix: 1f2e3d4c5d
>  
>   * Mark a regression as a duplicate of another one already tracked by regzbot::
>  
> 

Re: [PATCH 1/2] docs: *-regressions.rst: Use collon after regzbot introduced command

[Nícolas F. R. A. Prado]

On Mon, Mar 11, 2024 at 02:39:46PM +0100, Thorsten Leemhuis wrote:
> Thx for this!
> 
> On 08.03.24 15:09, Nícolas F. R. A. Prado wrote:
> > All the examples in the reference documentation for regzbot have a
> > collon
> 
> s/collon/colon/ here and a few lines below as well. And in the subject
> as well. Speaking of which: something like "docs: *-regressions.rst:
> add colon to regzbot commands" might be better.
> 
> > after the "introduced" command, while on the kernel documentation
> > some have and others don't. This suggests both are acceptable,
> 
> Yup.
> 
> > but in
> > order to avoid confusion, add collons after all the commands to match
> > the reference docs.
> 
> Yeah, good idea. I likely would have done this myself soon while doing a
> few other changes I plan, but whatever. :-D
> 
> > Link: https://gitlab.com/knurd42/regzbot/-/blob/main/docs/reference.md
> > Signed-off-by: Nícolas F. R. A. Prado <nfraprado@collabora.com>
> 
> With the changes above:
> 
> Reviewed-by: Thorsten Leemhuis <linux@leemhuis.info>
> 
> Side note: I wonder if the commit message could come a bit quicker to
> the point (something along the lines of "Use colons as command
> terminator everywhere for consistency, even if it not strictly
> necessary. That way it will also match regzbot's reference
> documentation.". But not really important I guess. Up to John.

Yep, all great suggestions, thanks. Will apply them for v2.

Thanks,
Nícolas