[PATCH v2] contributor-guide/submit-changes: encourage patch version changelogs

[PATCH v2] contributor-guide/submit-changes: encourage patch version changelogs

[Trevor Woerner]

Add a section after the 'git format-patch' information encouraging developers
to add patch version changelogs to their patch updates.

Signed-off-by: Trevor Woerner <twoerner@gmail.com>
---
changes in v2:
- clarify SoB line
- clarify "this patch was added in v2" line
---
 .../contributor-guide/submit-changes.rst      | 32 +++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/documentation/contributor-guide/submit-changes.rst b/documentation/contributor-guide/submit-changes.rst
index 0675aac984cf..6d5d69d7cfb4 100644
--- a/documentation/contributor-guide/submit-changes.rst
+++ b/documentation/contributor-guide/submit-changes.rst
@@ -776,6 +776,38 @@ argument to ``git format-patch`` with a version number::
 
    git format-patch -v2 <ref-branch>
 
+
+After generating updated patches (v2, v3, and so on) via ``git
+format-patch``, ideally developers will add a patch version changelog
+to each patch that describes what has changed between each revision of
+the patch. Add patch version changelogs after the ``---`` marker in the
+patch, indicating that this information is part of this patch, but is not
+suitable for inclusion in the commit message (i.e. the git history) itself.
+Providing a patch version changelog makes it easier for maintainers and
+reviewers to succinctly understand what changed in all versions of the
+patch, without having to consult alternate sources of information, such as
+searching through messages on a mailing list. For example::
+
+   <patch title>
+
+   <commit message>
+
+   <Signed-off-by/other trailers>
+   ---
+   changes in v4:
+   - provide a clearer commit message
+   - fix spelling mistakes
+
+   changes in v3:
+   - replace func() to use other_func() instead
+
+   changes in v2:
+   - this patch was added in v2
+   ---
+   <diffstat output>
+
+   <unified diff>
+
 Lastly please ensure that you also test your revised changes. In particular
 please don't just edit the patch file written out by ``git format-patch`` and
 resend it.
-- 
2.44.0.501.g19981daefd7c

Re: [docs] [PATCH v2] contributor-guide/submit-changes: encourage patch version changelogs

[Quentin Schulz]

Hi Trevor,

On 5/2/25 7:21 PM, Trevor Woerner via lists.yoctoproject.org wrote:
> Add a section after the 'git format-patch' information encouraging developers
> to add patch version changelogs to their patch updates.
> 
> Signed-off-by: Trevor Woerner <twoerner@gmail.com>
> ---
> changes in v2:
> - clarify SoB line
> - clarify "this patch was added in v2" line
> ---
>   .../contributor-guide/submit-changes.rst      | 32 +++++++++++++++++++
>   1 file changed, 32 insertions(+)
> 
> diff --git a/documentation/contributor-guide/submit-changes.rst b/documentation/contributor-guide/submit-changes.rst
> index 0675aac984cf..6d5d69d7cfb4 100644
> --- a/documentation/contributor-guide/submit-changes.rst
> +++ b/documentation/contributor-guide/submit-changes.rst
> @@ -776,6 +776,38 @@ argument to ``git format-patch`` with a version number::
>   
>      git format-patch -v2 <ref-branch>
>   
> +
> +After generating updated patches (v2, v3, and so on) via ``git
> +format-patch``, ideally developers will add a patch version changelog
> +to each patch that describes what has changed between each revision of

This is a bit different from what `b4` tool does by default, which is 
that it stores the changelog of the whole series in the cover letter 
instead of per-patch. They aren't incompatible per-se as you can add the 
per-patch changelog and b4 will happily take it, but it's a bit of a 
different workflow :)

Anyway, nothing specific to b4 in the docs right now, so a "problem" for 
later :)

> +the patch. Add patch version changelogs after the ``---`` marker in the
> +patch, indicating that this information is part of this patch, but is not
> +suitable for inclusion in the commit message (i.e. the git history) itself.
> +Providing a patch version changelog makes it easier for maintainers and
> +reviewers to succinctly understand what changed in all versions of the
> +patch, without having to consult alternate sources of information, such as
> +searching through messages on a mailing list. For example::
> +
> +   <patch title>
> +
> +   <commit message>
> +
> +   <Signed-off-by/other trailers>
> +   ---
> +   changes in v4:
> +   - provide a clearer commit message
> +   - fix spelling mistakes
> +
> +   changes in v3:
> +   - replace func() to use other_func() instead
> +
> +   changes in v2:
> +   - this patch was added in v2
> +   ---
> +   <diffstat output>
> +
> +   <unified diff>
> +

Looks good to me,

Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>

Thanks!
Quentin

Re: [PATCH v2] contributor-guide/submit-changes: encourage patch version changelogs

[Antonin Godard]

On Fri, 02 May 2025 13:21:43 -0400, Trevor Woerner wrote:
> Add a section after the 'git format-patch' information encouraging developers
> to add patch version changelogs to their patch updates.
> 
> 

Applied, thanks!

[1/1] contributor-guide/submit-changes: encourage patch version changelogs
      commit: 2e3a37c4607b296956993e557d1786c4876e5722

Best regards,
-- 
Antonin Godard <antonin.godard@bootlin.com>