On patch series version tags, and also cover letters (was: [PATCH v2 2/2] Added parameter to take screenshot with screendump as PNG)

[Markus Armbruster]

Kshitij Suri <kshitij.suri@nutanix.com> writes:

> On 29/03/22 12:12 pm, Markus Armbruster wrote:
>> If I count correctly, this is the fifth posting tagged "v2".  Don't do
>> that, please, as it's quite confusing.
>>
> Thank you for your review and I apologise for that since I am fairly
> new to upstreaming. As per what I read version updates should be done
> only when there are significant design changes to the patch which
> didn't happen in the v2 version. Will update it to v3 and send the
> patch.

We all make mistakes :)

The purpose of the version tag in the subject is to help humans with
keeping track of patch submissions.  Increment it for every submission.

If you need to resend a submission completely unchanged for some reason,
you may want to keep the tag and add "RESEND".

A cover letter (git format-patch --cover-letter) lets you write an
introduction to the whole series.  Simple series may not need an
introduction, but complex ones do.  I always use one except when the
"series" is a single patch.

Keeping a change log in the cover letter helps people who already
reviewed previous iterations.

Check out

    https://lists.gnu.org/archive/html/qemu-devel/2022-03/msg03977.html

for an example.  Not every cover letter needs to be that verbose, of
course.  Likewise, the level of detail in change logs varies.

A good way to get a feel for good cover letters and commit messages is
to review patches.  What kind of information helps you as a reviewer?
That's the kind of information you want to provide with your
submissions.

Hope this helps!