[PATCH net] docs: netdev: document the existence of the mail bot

[PATCH net] docs: netdev: document the existence of the mail bot

[Jakub Kicinski]

We had a good run, but after 4 weeks of use we heard someone
asking about pw-bot commands. Let's explain its existence
in the docs. It's not a complete documentation but hopefully
it's enough for the casual contributor. The project and scope
are in flux so the details would likely become out of date,
if we were to document more in depth.

Link: https://lore.kernel.org/all/20230522140057.GB18381@nucnuc.mle/
Signed-off-by: Jakub Kicinski <kuba@kernel.org>
---
CC: corbet@lwn.net
CC: linux-doc@vger.kernel.org
---
 Documentation/process/maintainer-netdev.rst | 33 ++++++++++++++++-----
 1 file changed, 26 insertions(+), 7 deletions(-)

diff --git a/Documentation/process/maintainer-netdev.rst b/Documentation/process/maintainer-netdev.rst
index f73ac9e175a8..83614cec9328 100644
--- a/Documentation/process/maintainer-netdev.rst
+++ b/Documentation/process/maintainer-netdev.rst
@@ -127,13 +127,32 @@ the value of ``Message-ID`` to the URL above.
 Updating patch status
 ~~~~~~~~~~~~~~~~~~~~~
 
-It may be tempting to help the maintainers and update the state of your
-own patches when you post a new version or spot a bug. Please **do not**
-do that.
-Interfering with the patch status on patchwork will only cause confusion. Leave
-it to the maintainer to figure out what is the most recent and current
-version that should be applied. If there is any doubt, the maintainer
-will reply and ask what should be done.
+Contributors and reviewers do not have the permissions to update patch
+state directly in patchwork. Patchwork doesn't expose much information
+about the history of the state of patches, therefore having multiple
+people update the state leads to confusion.
+
+Instead of delegating patchwork permissions netdev uses a simple mail
+bot which looks for special commands/lines within the emails sent to
+the mailing list. For example to mark a series as Changes Requested
+one needs to send the following line anywhere in the email thread::
+
+  pw-bot: changes-requested
+
+As a result the bot will set the entire series to Changes Requested.
+This may be useful when author discovers a bug in their own series
+and wants to prevent it from getting applied.
+
+The use of the bot is entirely optional, if in doubt ignore its existence
+completely. Maintainers will classify and update the state of the patches
+themselves. No email should ever be sent to the list with the main purpose
+of communicating with the bot, the bot commands should be seen as metadata.
+
+The use of the bot is restricted to authors of the patches (the ``From:``
+header on patch submission and command must match!), maintainers themselves
+and a handful of senior reviewers. Bot records its activity here:
+
+  https://patchwork.hopto.org/pw-bot.html
 
 Review timelines
 ~~~~~~~~~~~~~~~~
-- 
2.40.1

Re: [PATCH net] docs: netdev: document the existence of the mail bot

[Andrew Lunn]

On Mon, May 22, 2023 at 04:09:03PM -0700, Jakub Kicinski wrote:
> We had a good run, but after 4 weeks of use we heard someone
> asking about pw-bot commands. Let's explain its existence
> in the docs. It's not a complete documentation but hopefully
> it's enough for the casual contributor. The project and scope
> are in flux so the details would likely become out of date,
> if we were to document more in depth.
> 
> Link: https://lore.kernel.org/all/20230522140057.GB18381@nucnuc.mle/
> Signed-off-by: Jakub Kicinski <kuba@kernel.org>

Reviewed-by: Andrew Lunn <andrew@lunn.ch>

> +Instead of delegating patchwork permissions netdev uses a simple mail
> +bot which looks for special commands/lines within the emails sent to
> +the mailing list. For example to mark a series as Changes Requested
> +one needs to send the following line anywhere in the email thread::
> +
> +  pw-bot: changes-requested

...

> +  https://patchwork.hopto.org/pw-bot.html

[Evil grin]
So your patch did not trigger the bot. Lets see if my reply does?
[/Evil grin]

   Andrew

Re: [PATCH net] docs: netdev: document the existence of the mail bot

[Jakub Kicinski]

On Tue, 23 May 2023 03:46:46 +0200 Andrew Lunn wrote:
> > +Instead of delegating patchwork permissions netdev uses a simple mail
> > +bot which looks for special commands/lines within the emails sent to
> > +the mailing list. For example to mark a series as Changes Requested
> > +one needs to send the following line anywhere in the email thread::
> > +
> > +  pw-bot: changes-requested  
> 
> ...
> 
> > +  https://patchwork.hopto.org/pw-bot.html  
> 
> [Evil grin]
> So your patch did not trigger the bot. Lets see if my reply does?
> [/Evil grin]

Commands must be on separate lines, with no extra white space.
I wonder if that proves the documentation is insufficient :)

Re: [PATCH net] docs: netdev: document the existence of the mail bot

[Simon Horman]

On Mon, May 22, 2023 at 04:09:03PM -0700, Jakub Kicinski wrote:
> We had a good run, but after 4 weeks of use we heard someone
> asking about pw-bot commands. Let's explain its existence
> in the docs. It's not a complete documentation but hopefully
> it's enough for the casual contributor. The project and scope
> are in flux so the details would likely become out of date,
> if we were to document more in depth.
> 
> Link: https://lore.kernel.org/all/20230522140057.GB18381@nucnuc.mle/
> Signed-off-by: Jakub Kicinski <kuba@kernel.org>

Reviewed-by: Simon Horman <simon.horman@corigine.com>

Re: [PATCH net] docs: netdev: document the existence of the mail bot

[patchwork-bot+netdevbpf]

Hello:

This patch was applied to netdev/net.git (main)
by Jakub Kicinski <kuba@kernel.org>:

On Mon, 22 May 2023 16:09:03 -0700 you wrote:
> We had a good run, but after 4 weeks of use we heard someone
> asking about pw-bot commands. Let's explain its existence
> in the docs. It's not a complete documentation but hopefully
> it's enough for the casual contributor. The project and scope
> are in flux so the details would likely become out of date,
> if we were to document more in depth.
> 
> [...]

Here is the summary with links:
  - [net] docs: netdev: document the existence of the mail bot
    https://git.kernel.org/netdev/net/c/7e7b3b097a9d

You are awesome, thank you!
-- 
Deet-doot-dot, I am a bot.
https://korg.docs.kernel.org/patchwork/pwbot.html

Re: [PATCH net] docs: netdev: document the existence of the mail bot

[Martin Habets]

On Mon, May 22, 2023 at 07:05:15PM -0700, Jakub Kicinski wrote:
> On Tue, 23 May 2023 03:46:46 +0200 Andrew Lunn wrote:
> > > +Instead of delegating patchwork permissions netdev uses a simple mail
> > > +bot which looks for special commands/lines within the emails sent to
> > > +the mailing list. For example to mark a series as Changes Requested
> > > +one needs to send the following line anywhere in the email thread::
> > > +
> > > +  pw-bot: changes-requested  
> > 
> > ...
> > 
> > > +  https://patchwork.hopto.org/pw-bot.html  
> > 
> > [Evil grin]
> > So your patch did not trigger the bot. Lets see if my reply does?
> > [/Evil grin]
> 
> Commands must be on separate lines, with no extra white space.
> I wonder if that proves the documentation is insufficient :)

I did wonder if the space before pw-bot was mandatory as well,
but apparently not.
Good improvement, thanks for documenting this.

Martin