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

[Trevor Woerner <twoerner@gmail.com>]

On Tue 2025-03-18 @ 11:56:47 AM, Quentin Schulz wrote:
> Hi Trevor,
> 
> On 3/18/25 4:56 AM, 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>
> > ---
> >   .../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::
> > +
> 
> If you're looking at this from a maintainer perspective, maybe consider
> using b4.
> 
> For reviewing stuff, I sometimes do
> 
> b4 diff -v 1 2 -- <lore.kernel.org URL to v2>
> 
> and that helps.
> 
> This is orthogonal to this patch though but just wanted to mention it :)

Thanks for the reminder! I've been meaning to force myself to start using b4.
We're pretty lucky that our repositories are hosted on lore.kernel.org. We
even have our own lore repository at work internally, so b4 would be useful
there too.