[PATCH v1] doc: update guideline for fix commit messages

[PATCH v1] doc: update guideline for fix commit messages

[Sivaramakrishnan Venkat]

Maintainers remove the Cc author line when merging the patch.
So, the guidelines is updated with a suggestion for the placement
of Cc lines in a commit message for easy merging.

Signed-off-by: Sivaramakrishnan Venkat <venkatx.sivaramakrishnan@intel.com>
---
 doc/guides/contributing/patches.rst | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/doc/guides/contributing/patches.rst b/doc/guides/contributing/patches.rst
index e286d9e6d5..e109365599 100644
--- a/doc/guides/contributing/patches.rst
+++ b/doc/guides/contributing/patches.rst
@@ -275,6 +275,12 @@ Here are some guidelines for the body of a commit message:
 
      Signed-off-by: Alex Smith <alex.smith@example.com>
 
+* .. Note::
+
+     Maintainers remove the "Cc: author@example.com" line when merging the patch.
+     To help the maintainer, the submitter may move this line to the notes section
+     of the commit, after the ``---`` separator.
+
 * When fixing an error or warning it is useful to add the error message and instructions on how to reproduce it.
 
 * Use correct capitalization, punctuation and spelling.
-- 
2.25.1

Re: [PATCH v1] doc: update guideline for fix commit messages

[Ferruh Yigit]

On 1/25/2024 3:39 AM, Sivaramakrishnan Venkat wrote:
> Maintainers remove the Cc author line when merging the patch.
> So, the guidelines is updated with a suggestion for the placement
> of Cc lines in a commit message for easy merging.
> 
> Signed-off-by: Sivaramakrishnan Venkat <venkatx.sivaramakrishnan@intel.com>
> ---
>  doc/guides/contributing/patches.rst | 6 ++++++
>  1 file changed, 6 insertions(+)
> 
> diff --git a/doc/guides/contributing/patches.rst b/doc/guides/contributing/patches.rst
> index e286d9e6d5..e109365599 100644
> --- a/doc/guides/contributing/patches.rst
> +++ b/doc/guides/contributing/patches.rst
> @@ -275,6 +275,12 @@ Here are some guidelines for the body of a commit message:
>  
>       Signed-off-by: Alex Smith <alex.smith@example.com>
>  
> +* .. Note::
> +
> +     Maintainers remove the "Cc: author@example.com" line when merging the patch.
> +     To help the maintainer, the submitter may move this line to the notes section
> +     of the commit, after the ``---`` separator.
> +
>  * When fixing an error or warning it is useful to add the error message and instructions on how to reproduce it.
>  
>  * Use correct capitalization, punctuation and spelling.

Thanks Sivaramakrishnan for the doc update, that is practically what
happens,
but "Note" is to get additional attention, and there are already
multiple steps involved to prepare a commit log and this one is not
really that important, so lets not complicate it more for new contributors.

One option is add above information without ".. Note::" block, and
shorten it a little more, with adding the reasoning of adding "Cc:
author@example.com" (so I am asking adding more info and make paragraph
shorter :)

Other option is update samples to the desired format, it won't explain
the ask but imply it by showing requested output, as we are doing for
"Depends-on" tag.


I am for starting with the second option first, update samples, and see
if it improves things, what do you think?

[PATCH v2] doc: update guideline for fix commit messages

[Sivaramakrishnan Venkat]

Maintainers remove the Cc author line when merging the patch.
So, the guidelines is updated with a suggestion for the placement
of Cc lines in a commit message for easy merging.

Signed-off-by: Sivaramakrishnan Venkat <venkatx.sivaramakrishnan@intel.com>
---
v2:
   - Samples updated to the desired format for the "Cc:" line in the commit message
---
 doc/guides/contributing/patches.rst | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/doc/guides/contributing/patches.rst b/doc/guides/contributing/patches.rst
index e286d9e6d5..5687b5fa27 100644
--- a/doc/guides/contributing/patches.rst
+++ b/doc/guides/contributing/patches.rst
@@ -271,9 +271,10 @@ Here are some guidelines for the body of a commit message:
      Update the docs, fixing description of some parameter.
 
      Fixes: abcdefgh1234 ("doc: add some parameter")
-     Cc: author@example.com
 
      Signed-off-by: Alex Smith <alex.smith@example.com>
+     ---
+     Cc: author@example.com
 
 * When fixing an error or warning it is useful to add the error message and instructions on how to reproduce it.
 
-- 
2.25.1

Re: [PATCH v2] doc: update guideline for fix commit messages

[Ferruh Yigit]

On 1/30/2024 2:09 PM, Sivaramakrishnan Venkat wrote:
> Maintainers remove the Cc author line when merging the patch.
> So, the guidelines is updated with a suggestion for the placement
> of Cc lines in a commit message for easy merging.
> 
> Signed-off-by: Sivaramakrishnan Venkat <venkatx.sivaramakrishnan@intel.com>
> ---
> v2:
>    - Samples updated to the desired format for the "Cc:" line in the commit message
> ---
>  doc/guides/contributing/patches.rst | 3 ++-
>  1 file changed, 2 insertions(+), 1 deletion(-)
> 
> diff --git a/doc/guides/contributing/patches.rst b/doc/guides/contributing/patches.rst
> index e286d9e6d5..5687b5fa27 100644
> --- a/doc/guides/contributing/patches.rst
> +++ b/doc/guides/contributing/patches.rst
> @@ -271,9 +271,10 @@ Here are some guidelines for the body of a commit message:
>       Update the docs, fixing description of some parameter.
>  
>       Fixes: abcdefgh1234 ("doc: add some parameter")
> -     Cc: author@example.com
>  
>       Signed-off-by: Alex Smith <alex.smith@example.com>
> +     ---
> +     Cc: author@example.com
>  
>  * When fixing an error or warning it is useful to add the error message and instructions on how to reproduce it.
>  

There are multiple sample that has "Cc: author@example.com" line, can
you please update all for consistency?

[PATCH v3] doc: update guideline for fix commit messages

[Sivaramakrishnan Venkat]

Maintainers remove the Cc author line when merging the patch.
So, the guidelines is updated with a suggestion for the placement
of Cc lines in a commit message for easy merging.

Signed-off-by: Sivaramakrishnan Venkat <venkatx.sivaramakrishnan@intel.com>
---
v3:
  - Other samples updated to the desired format for the "Cc:" line in the commit message
v2:
  - Samples updated to the desired format for the "Cc:" line in the commit message
---
 doc/guides/contributing/patches.rst | 12 ++++++++----
 doc/guides/contributing/stable.rst  |  3 ++-
 2 files changed, 10 insertions(+), 5 deletions(-)

diff --git a/doc/guides/contributing/patches.rst b/doc/guides/contributing/patches.rst
index e286d9e6d5..4e1768025e 100644
--- a/doc/guides/contributing/patches.rst
+++ b/doc/guides/contributing/patches.rst
@@ -271,9 +271,10 @@ Here are some guidelines for the body of a commit message:
      Update the docs, fixing description of some parameter.
 
      Fixes: abcdefgh1234 ("doc: add some parameter")
-     Cc: author@example.com
 
      Signed-off-by: Alex Smith <alex.smith@example.com>
+     ---
+     Cc: author@example.com
 
 * When fixing an error or warning it is useful to add the error message and instructions on how to reproduce it.
 
@@ -300,9 +301,10 @@ in the body of the commit message. For example::
 
      Coverity issue: 12345
      Fixes: abcdefgh1234 ("doc: add some parameter")
-     Cc: author@example.com
 
      Signed-off-by: Alex Smith <alex.smith@example.com>
+     ---
+     Cc: author@example.com
 
 
 `Bugzilla <https://bugs.dpdk.org>`_
@@ -319,9 +321,10 @@ For example::
 
     Bugzilla ID: 12345
     Fixes: abcdefgh1234 ("doc: add some parameter")
-    Cc: author@example.com
 
     Signed-off-by: Alex Smith <alex.smith@example.com>
+    ---
+    Cc: author@example.com
 
 Patch for Stable Releases
 ~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -336,9 +339,10 @@ In the commit message body the Cc: stable@dpdk.org should be inserted as follows
      Update the docs, fixing description of some parameter.
 
      Fixes: abcdefgh1234 ("doc: add some parameter")
-     Cc: stable@dpdk.org
 
      Signed-off-by: Alex Smith <alex.smith@example.com>
+     ---
+     Cc: stable@dpdk.org
 
 For further information on stable contribution you can go to
 :doc:`Stable Contribution Guide <stable>`.
diff --git a/doc/guides/contributing/stable.rst b/doc/guides/contributing/stable.rst
index 8156b72b20..bf7f4bceec 100644
--- a/doc/guides/contributing/stable.rst
+++ b/doc/guides/contributing/stable.rst
@@ -92,9 +92,10 @@ commit message body as follows::
      Update the docs, fixing description of some parameter.
 
      Fixes: abcdefgh1234 ("doc: add some parameter")
-     Cc: stable@dpdk.org
 
      Signed-off-by: Alex Smith <alex.smith@example.com>
+     ---
+     Cc: stable@dpdk.org
 
 
 Fixes not suitable for backport should not include the ``Cc: stable@dpdk.org`` tag.
-- 
2.25.1

Re: [PATCH v3] doc: update guideline for fix commit messages

[Ferruh Yigit]

On 2/1/2024 1:48 PM, Sivaramakrishnan Venkat wrote:
> Maintainers remove the Cc author line when merging the patch.
> So, the guidelines is updated with a suggestion for the placement
> of Cc lines in a commit message for easy merging.
> 
> Signed-off-by: Sivaramakrishnan Venkat <venkatx.sivaramakrishnan@intel.com>
> ---
> v3:
>   - Other samples updated to the desired format for the "Cc:" line in the commit message
> v2:
>   - Samples updated to the desired format for the "Cc:" line in the commit message
> ---
>  doc/guides/contributing/patches.rst | 12 ++++++++----
>  doc/guides/contributing/stable.rst  |  3 ++-
>  2 files changed, 10 insertions(+), 5 deletions(-)
> 
> diff --git a/doc/guides/contributing/patches.rst b/doc/guides/contributing/patches.rst
> index e286d9e6d5..4e1768025e 100644
> --- a/doc/guides/contributing/patches.rst
> +++ b/doc/guides/contributing/patches.rst
> @@ -271,9 +271,10 @@ Here are some guidelines for the body of a commit message:
>       Update the docs, fixing description of some parameter.
>  
>       Fixes: abcdefgh1234 ("doc: add some parameter")
> -     Cc: author@example.com
>  
>       Signed-off-by: Alex Smith <alex.smith@example.com>
> +     ---
> +     Cc: author@example.com
>  
>  * When fixing an error or warning it is useful to add the error message and instructions on how to reproduce it.
>  
> @@ -300,9 +301,10 @@ in the body of the commit message. For example::
>  
>       Coverity issue: 12345
>       Fixes: abcdefgh1234 ("doc: add some parameter")
> -     Cc: author@example.com
>  
>       Signed-off-by: Alex Smith <alex.smith@example.com>
> +     ---
> +     Cc: author@example.com
>  
>  
>  `Bugzilla <https://bugs.dpdk.org>`_
> @@ -319,9 +321,10 @@ For example::
>  
>      Bugzilla ID: 12345
>      Fixes: abcdefgh1234 ("doc: add some parameter")
> -    Cc: author@example.com
>  
>      Signed-off-by: Alex Smith <alex.smith@example.com>
> +    ---
> +    Cc: author@example.com
>  
>  Patch for Stable Releases
>  ~~~~~~~~~~~~~~~~~~~~~~~~~
> @@ -336,9 +339,10 @@ In the commit message body the Cc: stable@dpdk.org should be inserted as follows
>       Update the docs, fixing description of some parameter.
>  
>       Fixes: abcdefgh1234 ("doc: add some parameter")
> -     Cc: stable@dpdk.org
>  
>       Signed-off-by: Alex Smith <alex.smith@example.com>
> +     ---
> +     Cc: stable@dpdk.org
>  

We want to keep "Cc: stable@dpdk.org" in the commit log, so above it wrong.

Please only update "Cc: author@example.com" cases.

[PATCH v4] doc: update guideline for fix commit messages

[Sivaramakrishnan Venkat]

Maintainers remove the Cc author line when merging the patch.
So, the guidelines is updated with a suggestion for the placement
of Cc lines in a commit message for easy merging.

Signed-off-by: Sivaramakrishnan Venkat <venkatx.sivaramakrishnan@intel.com>
---
v4:
  - Reverted removal of "Cc: stable@dpdk.org" in the commit log
v3:
  - Other samples updated to the desired format for the "Cc:" line in the commit message
v2:
  - Samples updated to the desired format for the "Cc:" line in the commit message
---
 doc/guides/contributing/patches.rst | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/doc/guides/contributing/patches.rst b/doc/guides/contributing/patches.rst
index e286d9e6d5..7605ea4d64 100644
--- a/doc/guides/contributing/patches.rst
+++ b/doc/guides/contributing/patches.rst
@@ -271,9 +271,10 @@ Here are some guidelines for the body of a commit message:
      Update the docs, fixing description of some parameter.
 
      Fixes: abcdefgh1234 ("doc: add some parameter")
-     Cc: author@example.com
 
      Signed-off-by: Alex Smith <alex.smith@example.com>
+     ---
+     Cc: author@example.com
 
 * When fixing an error or warning it is useful to add the error message and instructions on how to reproduce it.
 
@@ -300,9 +301,10 @@ in the body of the commit message. For example::
 
      Coverity issue: 12345
      Fixes: abcdefgh1234 ("doc: add some parameter")
-     Cc: author@example.com
 
      Signed-off-by: Alex Smith <alex.smith@example.com>
+     ---
+     Cc: author@example.com
 
 
 `Bugzilla <https://bugs.dpdk.org>`_
@@ -319,9 +321,10 @@ For example::
 
     Bugzilla ID: 12345
     Fixes: abcdefgh1234 ("doc: add some parameter")
-    Cc: author@example.com
 
     Signed-off-by: Alex Smith <alex.smith@example.com>
+    ---
+    Cc: author@example.com
 
 Patch for Stable Releases
 ~~~~~~~~~~~~~~~~~~~~~~~~~
-- 
2.25.1

Re: [PATCH v4] doc: update guideline for fix commit messages

[Ferruh Yigit]

On 2/8/2024 10:51 AM, Sivaramakrishnan Venkat wrote:
> Maintainers remove the Cc author line when merging the patch.
> So, the guidelines is updated with a suggestion for the placement
> of Cc lines in a commit message for easy merging.
> 
> Signed-off-by: Sivaramakrishnan Venkat <venkatx.sivaramakrishnan@intel.com>
>

Acked-by: Ferruh Yigit <ferruh.yigit@amd.com>

RE: [PATCH v4] doc: update guideline for fix commit messages

[Power, Ciara]

> -----Original Message-----
> From: Ferruh Yigit <ferruh.yigit@amd.com>
> Sent: Thursday, February 8, 2024 11:36 AM
> To: Sivaramakrishnan, VenkatX <venkatx.sivaramakrishnan@intel.com>
> Cc: dev@dpdk.org; Power, Ciara <ciara.power@intel.com>
> Subject: Re: [PATCH v4] doc: update guideline for fix commit messages
> 
> On 2/8/2024 10:51 AM, Sivaramakrishnan Venkat wrote:
> > Maintainers remove the Cc author line when merging the patch.
> > So, the guidelines is updated with a suggestion for the placement of
> > Cc lines in a commit message for easy merging.
> >
> > Signed-off-by: Sivaramakrishnan Venkat
> > <venkatx.sivaramakrishnan@intel.com>
> >
> 
> Acked-by: Ferruh Yigit <ferruh.yigit@amd.com>

Acked-by: Ciara Power <ciara.power@intel.com>

Re: [PATCH v4] doc: update guideline for fix commit messages

[Thomas Monjalon]

20/03/2024 10:59, Power, Ciara:
> From: Ferruh Yigit <ferruh.yigit@amd.com>
> > On 2/8/2024 10:51 AM, Sivaramakrishnan Venkat wrote:
> > > Maintainers remove the Cc author line when merging the patch.
> > > So, the guidelines is updated with a suggestion for the placement of
> > > Cc lines in a commit message for easy merging.
> > >
> > > Signed-off-by: Sivaramakrishnan Venkat
> > > <venkatx.sivaramakrishnan@intel.com>
> > >
> > 
> > Acked-by: Ferruh Yigit <ferruh.yigit@amd.com>
> 
> Acked-by: Ciara Power <ciara.power@intel.com>

Applied, thanks.