From 941f3a952771043f7ab1b9a9193fcad27613a486 Mon Sep 17 00:00:00 2001 From: Trevor Woerner Date: Fri, 2 May 2025 13:21:43 -0400 Subject: [PATCH] contributor-guide/submit-changes: encourage patch version changelogs Add a section after the 'git format-patch' information encouraging developers to add patch version changelogs to their patch updates. (From yocto-docs rev: 78fd3b3f1ec797dfe3648509a1945241b50640d5) Signed-off-by: Trevor Woerner Reviewed-by: Quentin Schulz Signed-off-by: Antonin Godard (cherry picked from commit 2e3a37c4607b296956993e557d1786c4876e5722) Signed-off-by: Antonin Godard Signed-off-by: Steve Sakoman --- .../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 0675aac984..6d5d69d7cf 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 + +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:: + + + + + + + --- + 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 + --- + + + + 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.