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

Trevor Woerner
2025-03-18T03:56:20Z

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>
---
.../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..5ade6ba5cdef 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>
+
+ <SoB/etc lines>
+ ---
+ changes in v4:
+ - provide a clearer commit message
+ - fix spelling mistakes
+
+ changes in v3:
+ - replace func() to use other_func() instead
+
+ changes in v2:
+ - added
+ ---
+ <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