From 40232dc020d3f360bb6052ed8bf8c54731669450 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: a9f9d53fa4a29e3cf846868567190425ffed8bf0) 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 da0668ebe9..68903ad7a8 100644 --- a/documentation/contributor-guide/submit-changes.rst +++ b/documentation/contributor-guide/submit-changes.rst @@ -735,6 +735,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.