[PATCH net-next] docs: netdev: add note about Changes Requested and revising commit messages

[PATCH net-next] docs: netdev: add note about Changes Requested and revising commit messages

[Jakub Kicinski]

One of the most commonly asked questions is "I answered all questions
and don't need to make any code changes, why was the patch not applied".
Document our time honored tradition of asking people to repost with
improved commit messages, to record the answers to reviewer questions.

Take this opportunity to also recommend a change log format.

Signed-off-by: Jakub Kicinski <kuba@kernel.org>
---
I couldn't come up with a real example of the commit message.
LMK if the fake one is too silly :)

CC: sean.anderson@seco.com
CC: corbet@lwn.net
CC: linux-doc@vger.kernel.org
---
 Documentation/process/maintainer-netdev.rst | 29 +++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/Documentation/process/maintainer-netdev.rst b/Documentation/process/maintainer-netdev.rst
index 4a75686d35ab..4d109d92f40d 100644
--- a/Documentation/process/maintainer-netdev.rst
+++ b/Documentation/process/maintainer-netdev.rst
@@ -109,6 +109,8 @@ Finally, the vX.Y gets released, and the whole cycle starts over.
 netdev patch review
 -------------------
 
+.. _patch_status:
+
 Patch status
 ~~~~~~~~~~~~
 
@@ -143,6 +145,33 @@ Asking the maintainer for status updates on your
 patch is a good way to ensure your patch is ignored or pushed to the
 bottom of the priority list.
 
+Changes requested
+~~~~~~~~~~~~~~~~~
+
+Patches :ref:`marked<patch_status>` as ``Changes Requested`` need
+to be revised. The new version should come with a change log,
+preferably including links to previous postings, for example::
+
+  [PATCH net-next v3] net: make cows go moo
+
+  Even users who don't drink milk appreciate hearing the cows go "moo".
+
+  The amount of mooing will depend on packet rate so should match
+  the diurnal cycle quite well.
+
+  Signed-of-by: Joe Defarmer <joe@barn.org>
+  ---
+  v3:
+    - add a note about time-of-day mooing fluctuation to the commit message
+  v2: https://lore.kernel.org/netdev/123themessageid@barn.org/
+    - fix missing argument in kernel doc for netif_is_bovine()
+    - fix memory leak in netdev_register_cow()
+  v1: https://lore.kernel.org/netdev/456getstheclicks@barn.org/
+
+Commit message should be revised to answer any questions reviewers
+had to ask in previous discussions. Occasionally the update of
+the commit message will be the only change in the new version.
+
 Partial resends
 ~~~~~~~~~~~~~~~
 
-- 
2.39.2

Re: [PATCH net-next] docs: netdev: add note about Changes Requested and revising commit messages

[Randy Dunlap]

On 3/22/23 16:12, Jakub Kicinski wrote:
> One of the most commonly asked questions is "I answered all questions
> and don't need to make any code changes, why was the patch not applied".
> Document our time honored tradition of asking people to repost with
> improved commit messages, to record the answers to reviewer questions.
> 
> Take this opportunity to also recommend a change log format.
> 
> Signed-off-by: Jakub Kicinski <kuba@kernel.org>
> ---
> I couldn't come up with a real example of the commit message.
> LMK if the fake one is too silly :)

FWIW I like it.

> 
> CC: sean.anderson@seco.com
> CC: corbet@lwn.net
> CC: linux-doc@vger.kernel.org
> ---
>  Documentation/process/maintainer-netdev.rst | 29 +++++++++++++++++++++
>  1 file changed, 29 insertions(+)
> 
> diff --git a/Documentation/process/maintainer-netdev.rst b/Documentation/process/maintainer-netdev.rst
> index 4a75686d35ab..4d109d92f40d 100644
> --- a/Documentation/process/maintainer-netdev.rst
> +++ b/Documentation/process/maintainer-netdev.rst
> @@ -109,6 +109,8 @@ Finally, the vX.Y gets released, and the whole cycle starts over.
>  netdev patch review
>  -------------------
>  
> +.. _patch_status:
> +
>  Patch status
>  ~~~~~~~~~~~~
>  
> @@ -143,6 +145,33 @@ Asking the maintainer for status updates on your
>  patch is a good way to ensure your patch is ignored or pushed to the
>  bottom of the priority list.
>  
> +Changes requested
> +~~~~~~~~~~~~~~~~~
> +
> +Patches :ref:`marked<patch_status>` as ``Changes Requested`` need
> +to be revised. The new version should come with a change log,
> +preferably including links to previous postings, for example::
> +
> +  [PATCH net-next v3] net: make cows go moo
> +
> +  Even users who don't drink milk appreciate hearing the cows go "moo".
> +
> +  The amount of mooing will depend on packet rate so should match
> +  the diurnal cycle quite well.
> +
> +  Signed-of-by: Joe Defarmer <joe@barn.org>
> +  ---
> +  v3:
> +    - add a note about time-of-day mooing fluctuation to the commit message
> +  v2: https://lore.kernel.org/netdev/123themessageid@barn.org/
> +    - fix missing argument in kernel doc for netif_is_bovine()
> +    - fix memory leak in netdev_register_cow()
> +  v1: https://lore.kernel.org/netdev/456getstheclicks@barn.org/
> +
> +Commit message should be revised to answer any questions reviewers

The commit message should be

> +had to ask in previous discussions. Occasionally the update of

asked in previous discussions.

> +the commit message will be the only change in the new version.
> +
>  Partial resends
>  ~~~~~~~~~~~~~~~
>  

-- 
~Randy

Re: [PATCH net-next] docs: netdev: add note about Changes Requested and revising commit messages

[Jakub Kicinski]

On Wed, 22 Mar 2023 16:38:53 -0700 Randy Dunlap wrote:
> > +had to ask in previous discussions. Occasionally the update of  
> 
> asked in previous discussions.

"had to ask" as in were forced to ask due to a poor commit message,
is that not a valid use of "had to"?

Re: [PATCH net-next] docs: netdev: add note about Changes Requested and revising commit messages

[Randy Dunlap]

On 3/22/23 18:06, Jakub Kicinski wrote:
> On Wed, 22 Mar 2023 16:38:53 -0700 Randy Dunlap wrote:
>>> +had to ask in previous discussions. Occasionally the update of  
>>
>> asked in previous discussions.
> 
> "had to ask" as in were forced to ask due to a poor commit message,
> is that not a valid use of "had to"?

Oh, that's OK. I didn't get that from reading it.
Thanks.

-- 
~Randy

Re: [PATCH net-next] docs: netdev: add note about Changes Requested and revising commit messages

[patchwork-bot+netdevbpf]

Hello:

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

On Wed, 22 Mar 2023 16:12:02 -0700 you wrote:
> One of the most commonly asked questions is "I answered all questions
> and don't need to make any code changes, why was the patch not applied".
> Document our time honored tradition of asking people to repost with
> improved commit messages, to record the answers to reviewer questions.
> 
> Take this opportunity to also recommend a change log format.
> 
> [...]

Here is the summary with links:
  - [net-next] docs: netdev: add note about Changes Requested and revising commit messages
    https://git.kernel.org/netdev/net-next/c/e110ba659271

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