threads / patch / 56496

patchMyFirstContribution: Document --range-diff option when writing v2

Subject: [PATCH] MyFirstContribution: Document --range-diff option when writing v2

## tl;dr

22 messages between Sep 13, 2021 and Sep 23, 2021. Diffs are folded; open one to read it.

replies: 21people: 5as markdown or json

Glen Choo· Sep 13, 2021, 19:48 UTC · lore

In the "Sending V2" section, readers are directed to create v2 patches without using --range-diff. However, it is custom to include a range diff against the v1 patches as a reviewer aid.

Update the "Sending V2" section to include the --range-diff option. Also include some explanation for -v2 and --range-diff to help the reader understand the importance.

Signed-off-by: Glen Choo <chooglen@google.com>
---
 Documentation/MyFirstContribution.txt | 29 ++++++++++++++++++++-------
 1 file changed, 22 insertions(+), 7 deletions(-)
Show changes to Documentation/MyFirstContribution.txt +22 −7
diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
index 015cf24631..add1c2bba9 100644
--- a/Documentation/MyFirstContribution.txt
+++ b/Documentation/MyFirstContribution.txt
@@ -1033,18 +1033,33 @@ Skip ahead to <<reviewing,Responding to Reviews>> for information on how to
 handle comments from reviewers. Continue this section when your topic branch is
 shaped the way you want it to look for your patchset v2.
 
-When you're ready with the next iteration of your patch, the process is fairly
-similar.
+Let's write v2 as its own topic branch, because this will make some things more
+convenient later on. Create the `psuh-v2` branch like so:
 
-First, generate your v2 patches again:
+----
+$ git checkout -b psuh-v2 psuh
+----
+
+When you're ready with the next iteration of your patch, the process is fairly
+similar to before. Generate your patches again, but with some new flags:
 
 ----
-$ git format-patch -v2 --cover-letter -o psuh/ master..psuh
+$ git format-patch -v2 --range-diff psuh..psuh-v2 --cover-letter -o psuh/ master..psuh
 ----
 
-This will add your v2 patches, all named like `v2-000n-my-commit-subject.patch`,
-to the `psuh/` directory. You may notice that they are sitting alongside the v1
-patches; that's fine, but be careful when you are ready to send them.
+The `--range-diff psuh..psuh-v2` parameter tells `format-patch` to include a
+range diff between `psuh` and `psuh-v2`. This helps tell reviewers about the
+differences between your v1 and v2 patches.
+
+The `-v2` parameter tells `format-patch` to output "v2" patches. For instance,
+you may notice that your v2 patches, are all named like
+`v2-000n-my-commit-subject.patch`. `-v2` will also format your patches by
+prefixing them with "[PATCH V2]" instead of "[PATCH]", and your range-diff will
+be prefaced with "Range-diff against v1".
+
+Afer you run this command, `format-patch` will output the patches to the `psuh/`
+directory, alongside the v1 patches. That's fine, but be careful when you are
+ready to send them.
 
 Edit your cover letter again. Now is a good time to mention what's different
 between your last version and now, if it's something significant. You do not

-- 
2.33.0.309.g3052b89438-goog
Eric Sunshine· Sep 13, 2021, 20:00 UTC · re: Glen Choo · lore

Re: [PATCH] MyFirstContribution: Document --range-diff option when writing v2

On Mon, Sep 13, 2021 at 3:48 PM Glen Choo <chooglen@google.com> wrote:
Show 7 quoted lines
> In the "Sending V2" section, readers are directed to create v2 patches
> without using --range-diff. However, it is custom to include a range
> diff against the v1 patches as a reviewer aid.
>
> Update the "Sending V2" section to include the --range-diff option. Also
> include some explanation for -v2 and --range-diff to help the reader
> understand the importance.
Makes sense. A few minor comments below...
Show 13 quoted lines
> Signed-off-by: Glen Choo <chooglen@google.com>
> ---
> diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
> @@ -1033,18 +1033,33 @@ Skip ahead to <<reviewing,Responding to Reviews>> for information on how to
> -When you're ready with the next iteration of your patch, the process is fairly
> -similar.
> +Let's write v2 as its own topic branch, because this will make some things more
> +convenient later on. Create the `psuh-v2` branch like so:
>
> -First, generate your v2 patches again:
> +----
> +$ git checkout -b psuh-v2 psuh
> +----

These days, we're generally promote `git switch -c psuh-v2 psuh` rather than `git branch -b`. However, since the document already uses `git branch -b` elsewhere, the use here is probably acceptable. (An alternative would be to make this a two-patch series in which the first patch changes `git branch -b` over to `git switch -c`.)

Show 7 quoted lines
> +When you're ready with the next iteration of your patch, the process is fairly
> +similar to before. Generate your patches again, but with some new flags:
>
>  ----
> -$ git format-patch -v2 --cover-letter -o psuh/ master..psuh
> +$ git format-patch -v2 --range-diff psuh..psuh-v2 --cover-letter -o psuh/ master..psuh
>  ----

As long as both versions have the same base, it's generally easier to say merely `--range-diff=psuh` -- that is, you want a range-diff against `psuh` -- than to spell out the range explicitly. However, perhaps spelling out the range here has some pedagogical value, so maybe this is okay as-is.

> +The `--range-diff psuh..psuh-v2` parameter tells `format-patch` to include a
> +range diff between `psuh` and `psuh-v2`. This helps tell reviewers about the
> +differences between your v1 and v2 patches.

I think we usually spell it as "range-diff", not "range diff". Also, it might be a good idea to give some hint as to what a range-diff is, even if that hint is just a link to the `git range-diff` manual page. Maybe:

    ...to include a range-diff (see linkgit:range-diff[1]) between...
Eric Sunshine· Sep 13, 2021, 20:05 UTC · re: Eric Sunshine · lore

Re: [PATCH] MyFirstContribution: Document --range-diff option when writing v2

On Mon, Sep 13, 2021 at 4:00 PM Eric Sunshine <sunshine@sunshineco.com> wrote:
Show 6 quoted lines
> I think we usually spell it as "range-diff", not "range diff". Also,
> it might be a good idea to give some hint as to what a range-diff is,
> even if that hint is just a link to the `git range-diff` manual page.
> Maybe:
>
>     ...to include a range-diff (see linkgit:range-diff[1]) between...
Of course, I meant:
    ...to include a range-diff (see linkgit:git-range-diff[1]) between...
Junio C Hamano· Sep 13, 2021, 21:39 UTC · re: Glen Choo · lore

Re: [PATCH] MyFirstContribution: Document --range-diff option when writing v2

Glen Choo <chooglen@google.com> writes:
Show 6 quoted lines
> +Let's write v2 as its own topic branch, because this will make some things more
> +convenient later on. Create the `psuh-v2` branch like so:
>  
> +----
> +$ git checkout -b psuh-v2 psuh
> +----

What's missing here is on which branch this new description expects the user to work on. From its name, I am assuming that psuh-v2 will be modified while leaving psuh untouched, but spell your expectation out.

The following review is based on the assumption that the user is expected to futz with psuh-v2, leaving psuh intact. If that is not the case, it is a strong sign that you caused confusion on one reader by not spelling out your expectation.

I do not think it is a good suggestion at all to use a new topic branch, especially a one that forked from the tip of the original submission, and work on that branch to produce the new round. It would be much better to create a topic branch or a lightweight tag "psuh-v1" that points at the old tip and keep working on the same branch. But that is a separate story.

Show 7 quoted lines
> +When you're ready with the next iteration of your patch, the process is fairly
> +similar to before. Generate your patches again, but with some new flags:
>  
>  ----
> -$ git format-patch -v2 --cover-letter -o psuh/ master..psuh
> +$ git format-patch -v2 --range-diff psuh..psuh-v2 --cover-letter -o psuh/ master..psuh
>  ----

Before the "Generate your patches again", there would have been "rebase -i" of the original commits that went into "psuh" (v1).

But you do not necessarily have to touch all the commits during "rebase -i" session. What happens when the first few commits did not need to be touched?

Since the --range-diff says psuh..psuh-v2, these early and unmodified commits are excluded from the range, no? That would mean what appears to be commit #1 in the range-diff on the new side would not be the [PATCH 1/n] of the output, no?

And the command line says to format master..psuh, which is puzzling. Shouldn't it format the updated psuh-v2 branch?

> +The `--range-diff psuh..psuh-v2` parameter tells `format-patch` to include a
> +range diff between `psuh` and `psuh-v2`. This helps tell reviewers about the
> +differences between your v1 and v2 patches.

See above. The range-diff may fail to tell the fact that there are a few bottommost commits that are the same by omitting them.

Perhaps it would make it easier to manage if we used psuh-v1 as the anchoring point to represent where the tip of the last round was?

With something like:
	$ git checkout psuh
	$ git branch psuh-v1 ;# optional -- "git tag" is also OK.
	... work work work with "rebase -i" ...
	$ git format-patch -v2 --cover-letter -o psuh/ \
		--range-diff master..psuh-v1 master..
	# ..psuh-v1 can be ..@{yesterday} or whatever reflog reference

we do not have to worry if "rebase -i" left the bottommost commits untouched or silly things like that.

Show 9 quoted lines
> +The `-v2` parameter tells `format-patch` to output "v2" patches. For instance,
> +you may notice that your v2 patches, are all named like
> +`v2-000n-my-commit-subject.patch`. `-v2` will also format your patches by
> +prefixing them with "[PATCH V2]" instead of "[PATCH]", and your range-diff will
> +be prefaced with "Range-diff against v1".
> +
> +Afer you run this command, `format-patch` will output the patches to the `psuh/`
> +directory, alongside the v1 patches. That's fine, but be careful when you are
> +ready to send them.
It is unclear what "That's fine, but" is trying to convey.
I'd replace it with something like:
	You can refer to the old v1 patches while giving the final
	proofreading on the v2 patches, but you now need to say "git
	send-email psuh/v2-*.patch" to send them out ("*.patch" would
	match both v1 and v2 patches).
Thanks.
Glen Choo· Sep 14, 2021, 17:21 UTC · re: Junio C Hamano · lore

Re: [PATCH] MyFirstContribution: Document --range-diff option when writing v2

On Mon, Sep 13, 2021 at 02:39:39PM -0700, Junio C Hamano wrote:
Show 9 quoted lines
> What's missing here is on which branch this new description expects
> the user to work on.  From its name, I am assuming that psuh-v2 will
> be modified while leaving psuh untouched, but spell your expectation
> out.
> 
> The following review is based on the assumption that the user is
> expected to futz with psuh-v2, leaving psuh intact.  If that is not
> the case, it is a strong sign that you caused confusion on one
> reader by not spelling out your expectation.

That's fair, I was suggesting a specific workflow and should have been more explicit.

Show 6 quoted lines
> I do not think it is a good suggestion at all to use a new topic
> branch, especially a one that forked from the tip of the original
> submission, and work on that branch to produce the new round.  It
> would be much better to create a topic branch or a lightweight tag
> "psuh-v1" that points at the old tip and keep working on the same
> branch.  But that is a separate story.

Given that this is a "my first contribution" guide, I think it would be beneficial to be at least mildly opinionated on the workflow. Since the specifics of range-diff would depend on the workflow we choose to promote, it would be nice to make it as helpful as possible the first time around.

That is to say, I'd really appreciate your thoughts on your recommended workflow and I'd like to structure my additions around your recommendation :) What I've documented is just my own workflow, but I'm sure you have more insight into this area.

Show 8 quoted lines
> But you do not necessarily have to touch all the commits during
> "rebase -i" session.  What happens when the first few commits did
> not need to be touched?
> 
> Since the --range-diff says psuh..psuh-v2, these early and
> unmodified commits are excluded from the range, no?  That would mean
> what appears to be commit #1 in the range-diff on the new side would
> not be the [PATCH 1/n] of the output, no?
Yes, good catch. This was an oversight on my part.
Show 10 quoted lines
> Perhaps it would make it easier to manage if we used psuh-v1 as the
> anchoring point to represent where the tip of the last round was?
> 
> With something like:
> 
> 	$ git checkout psuh
> 	$ git branch psuh-v1 ;# optional -- "git tag" is also OK.
> 	... work work work with "rebase -i" ...
> 	$ git format-patch -v2 --cover-letter -o psuh/ \
> 		--range-diff master..psuh-v1 master..
Having an explicit psuh-v1 is a good idea.
> 	# ..psuh-v1 can be ..@{yesterday} or whatever reflog reference

If we make it clear that psuh-v1 is just the tip of the last round, perhaps the readers who would do this can already infer this from context, and we can omit the comment for brevity?

Show 5 quoted lines
> > +Afer you run this command, `format-patch` will output the patches to the `psuh/`
> > +directory, alongside the v1 patches. That's fine, but be careful when you are
> > +ready to send them.
> 
> It is unclear what "That's fine, but" is trying to convey.
Very valid.
Show 6 quoted lines
> I'd replace it with something like:
> 
> 	You can refer to the old v1 patches while giving the final
> 	proofreading on the v2 patches, but you now need to say "git
> 	send-email psuh/v2-*.patch" to send them out ("*.patch" would
> 	match both v1 and v2 patches).

Here, I have to confess that I'm not sure why the guide reuses the psuh/ directory. When I was first going through this, having v1 and v2 patches in the same directory seemed like a risky default because of the inherent risk of sending both v1 and v2 together.

I believe the unspoken intent is that having v1 patches in the same directory as v2 patches makes it easy to refer to both versions, and in turn, this promotes better quality discussion between v1 and v2. There might be other strong reasons to reuse the directory, but these are not obvious to me from reading this guide alone. It would be helpful to make these reasons explicit to the reader.

Junio C Hamano· Sep 14, 2021, 21:39 UTC · re: Glen Choo · lore

Re: [PATCH] MyFirstContribution: Document --range-diff option when writing v2

Glen Choo <chooglen@google.com> writes:
>> 	$ git format-patch -v2 --cover-letter -o psuh/ \
>> 		--range-diff master..psuh-v1 master..
>
> Having an explicit psuh-v1 is a good idea.

I think what's good idea is not explicit psuh-v1 but taking the range from the upstream (i.e. "master"), not "psuh" (which assumes that symmetric difference will cover everything, which may not necessarily be the case).

Show 5 quoted lines
>> 	# ..psuh-v1 can be ..@{yesterday} or whatever reflog reference
>
> If we make it clear that psuh-v1 is just the tip of the last round, perhaps the
> readers who would do this can already infer this from context, and we can omit
> the comment for brevity?

Oh absolutely. These #comments were meant for your consumption and not as a suggestion to be placed in the final text given to the end users.

> I believe the unspoken intent is that having v1 patches in the same directory as
> v2 patches makes it easy to refer to both versions, and in turn, this promotes
> better quality discussion between v1 and v2.
Separate directories may make it easier to do:
    diff -u psuh-v1/ pshu-v2/
as
    cd psuh && diff -u v1* v2*

would NOT work, but comparing patch e-mails textually, especially after the order of the patches or title of them got updated, won't be so useful an operation anyway.

When you have multiple topics in flight, you want your psuh topic in a single directory (perhaps differentiating the iterations with v$n prefix, or you can choose to have a subdirectory v1, v2, etc. in that directory) that is different from the directory for your plul topic, instead of flat collection of directories for psuh-v1, psuh-v2 and plul-v1 topic-iterations.

Bagas Sanjaya· Sep 14, 2021, 02:43 UTC · re: Glen Choo · lore

Re: [PATCH] MyFirstContribution: Document --range-diff option when writing v2

On 14/09/21 02.48, Glen Choo wrote:
Show 7 quoted lines
> In the "Sending V2" section, readers are directed to create v2 patches
> without using --range-diff. However, it is custom to include a range
> diff against the v1 patches as a reviewer aid.
> 
> Update the "Sending V2" section to include the --range-diff option. Also
> include some explanation for -v2 and --range-diff to help the reader
> understand the importance.

I think plain "Changes since v1 [link]" is sufficient if you can describe such changes well without resorting to range-diff.

-- 
An old man doll... just what I always wanted! - Clara
Eric Sunshine· Sep 14, 2021, 03:46 UTC · re: Bagas Sanjaya · lore

Re: [PATCH] MyFirstContribution: Document --range-diff option when writing v2

On Mon, Sep 13, 2021 at 10:43 PM Bagas Sanjaya <bagasdotme@gmail.com> wrote:
Show 11 quoted lines
> On 14/09/21 02.48, Glen Choo wrote:
> > In the "Sending V2" section, readers are directed to create v2 patches
> > without using --range-diff. However, it is custom to include a range
> > diff against the v1 patches as a reviewer aid.
> >
> > Update the "Sending V2" section to include the --range-diff option. Also
> > include some explanation for -v2 and --range-diff to help the reader
> > understand the importance.
>
> I think plain "Changes since v1 [link]" is sufficient if you can
> describe such changes well without resorting to range-diff.

Not so. Anyone who does any serious amount of review on this project finds it tremendously helpful to have both a prose description of the changes ("Changes since v1..." plus a link to the previous submission) and a mechanical range-diff or interdiff. A range-diff (or interdiff) is especially important to provide reviewers with context which they might have forgotten since the previous version of a patch series was posted, which can matter since it's so easy to forget specifics even about one's own review if enough time has passed or if reviewing a large number of unrelated submissions. A range-diff or interdiff also helps a reviewer determine at-a-glance whether or not earlier review comments have been addressed without having to laboriously re-read each and every patch.

Bagas Sanjaya· Sep 14, 2021, 03:55 UTC · re: Eric Sunshine · lore

Re: [PATCH] MyFirstContribution: Document --range-diff option when writing v2

On 14/09/21 10.46, Eric Sunshine wrote:
Show 13 quoted lines
> Not so. Anyone who does any serious amount of review on this project
> finds it tremendously helpful to have both a prose description of the
> changes ("Changes since v1..." plus a link to the previous submission)
> and a mechanical range-diff or interdiff. A range-diff (or interdiff)
> is especially important to provide reviewers with context which they
> might have forgotten since the previous version of a patch series was
> posted, which can matter since it's so easy to forget specifics even
> about one's own review if enough time has passed or if reviewing a
> large number of unrelated submissions. A range-diff or interdiff also
> helps a reviewer determine at-a-glance whether or not earlier review
> comments have been addressed without having to laboriously re-read
> each and every patch.
> 
So will range-diff be mandatory or optional?
-- 
An old man doll... just what I always wanted! - Clara
Glen Choo· Sep 20, 2021, 22:32 UTC · re: Glen Choo · lore

[PATCH v2] MyFirstContribution: Document --range-diff option when writing v2

In the "Sending v2" section, readers are directed to create v2 patches without using --range-diff. However, it is customary to include a range-diff against the v1 patches as a reviewer aid.

Update the "Sending v2" section to suggest a simple workflow that uses the --range-diff option. Also include some explanation for -v2 and --range-diff to help the reader understand the importance.

Signed-off-by: Glen Choo <chooglen@google.com>
---
Thanks for the helpful comments on v1! v2 aims to clear up other
ambiguities from v1 and to propose a specific workflow for readers.
Changes since v1:
* recommend that readers reuse the `psuh` topic branch for v2
* recommend that readers mark their v1 topic branch
* add a link to the range-diff docs
* change the v2 glob pattern to `psuh/v2-*.patch` to match the v1 example
* explicitly call out the v2 glob pattern so that readers will be extra
  careful
Interdiff against v1:
  diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
  index add1c2bba9..790bf1e8b5 100644
  --- a/Documentation/MyFirstContribution.txt
  +++ b/Documentation/MyFirstContribution.txt
  @@ -1029,27 +1029,29 @@ kidding - be patient!)
   [[v2-git-send-email]]
   === Sending v2
   
  -Skip ahead to <<reviewing,Responding to Reviews>> for information on how to
  -handle comments from reviewers. Continue this section when your topic branch is
  -shaped the way you want it to look for your patchset v2.
  +This section will focus on how to send a v2 of your patchset. To learn what
  +should go into v2, skip ahead to <<reviewing,Responding to Reviews>> for
  +information on how to handle comments from reviewers.
   
  -Let's write v2 as its own topic branch, because this will make some things more
  -convenient later on. Create the `psuh-v2` branch like so:
  +We'll reuse our `psuh` topic branch for v2. Before we make any changes, we'll
  +mark the tip of our v1 branch for easy reference:
   
   ----
  -$ git checkout -b psuh-v2 psuh
  +$ git checkout psuh
  +$ git branch psuh-v1
   ----
   
  -When you're ready with the next iteration of your patch, the process is fairly
  -similar to before. Generate your patches again, but with some new flags:
  +Make your changes with `git rebase -i`. Once you're ready with the next
  +iteration of your patch, the process is fairly similar to before. Generate your
  +patches again, but with some new flags:
   
   ----
  -$ git format-patch -v2 --range-diff psuh..psuh-v2 --cover-letter -o psuh/ master..psuh
  +$ git format-patch -v2 --cover-letter -o psuh/ --range-diff master..psuh-v1 master..
   ----
   
  -The `--range-diff psuh..psuh-v2` parameter tells `format-patch` to include a
  -range diff between `psuh` and `psuh-v2`. This helps tell reviewers about the
  -differences between your v1 and v2 patches.
  +The `--range-diff master..psuh-v1` parameter tells `format-patch` to include a
  +range-diff between `psuh-v1` and `psuh` (see linkgit:git-range-diff[1]). This
  +helps tell reviewers about the differences between your v1 and v2 patches.
   
   The `-v2` parameter tells `format-patch` to output "v2" patches. For instance,
   you may notice that your v2 patches, are all named like
  @@ -1058,8 +1060,10 @@ prefixing them with "[PATCH V2]" instead of "[PATCH]", and your range-diff will
   be prefaced with "Range-diff against v1".
   
   Afer you run this command, `format-patch` will output the patches to the `psuh/`
  -directory, alongside the v1 patches. That's fine, but be careful when you are
  -ready to send them.
  +directory, alongside the v1 patches. Using a single directory makes it easy to
  +refer to the old v1 patches while proofreading the v2 patches, but you will need
  +to be careful to send out only the v2 patches. We will use a pattern like
  +"psuh/v2-*.patch" ("psuh/*.patch" would match v1 and v2 patches).
   
   Edit your cover letter again. Now is a good time to mention what's different
   between your last version and now, if it's something significant. You do not
  @@ -1097,7 +1101,7 @@ to the command:
   ----
   $ git send-email --to=target@example.com
   		 --in-reply-to="<foo.12345.author@example.com>"
  -		 psuh/v2*
  +		 psuh/v2-*.patch
   ----
   
   [[single-patch]]
 Documentation/MyFirstContribution.txt | 41 ++++++++++++++++++++-------
 1 file changed, 30 insertions(+), 11 deletions(-)
Show changes to Documentation/MyFirstContribution.txt +30 −11
diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
index 015cf24631..790bf1e8b5 100644
--- a/Documentation/MyFirstContribution.txt
+++ b/Documentation/MyFirstContribution.txt
@@ -1029,22 +1029,41 @@ kidding - be patient!)
 [[v2-git-send-email]]
 === Sending v2
 
-Skip ahead to <<reviewing,Responding to Reviews>> for information on how to
-handle comments from reviewers. Continue this section when your topic branch is
-shaped the way you want it to look for your patchset v2.
+This section will focus on how to send a v2 of your patchset. To learn what
+should go into v2, skip ahead to <<reviewing,Responding to Reviews>> for
+information on how to handle comments from reviewers.
+
+We'll reuse our `psuh` topic branch for v2. Before we make any changes, we'll
+mark the tip of our v1 branch for easy reference:
 
-When you're ready with the next iteration of your patch, the process is fairly
-similar.
+----
+$ git checkout psuh
+$ git branch psuh-v1
+----
 
-First, generate your v2 patches again:
+Make your changes with `git rebase -i`. Once you're ready with the next
+iteration of your patch, the process is fairly similar to before. Generate your
+patches again, but with some new flags:
 
 ----
-$ git format-patch -v2 --cover-letter -o psuh/ master..psuh
+$ git format-patch -v2 --cover-letter -o psuh/ --range-diff master..psuh-v1 master..
 ----
 
-This will add your v2 patches, all named like `v2-000n-my-commit-subject.patch`,
-to the `psuh/` directory. You may notice that they are sitting alongside the v1
-patches; that's fine, but be careful when you are ready to send them.
+The `--range-diff master..psuh-v1` parameter tells `format-patch` to include a
+range-diff between `psuh-v1` and `psuh` (see linkgit:git-range-diff[1]). This
+helps tell reviewers about the differences between your v1 and v2 patches.
+
+The `-v2` parameter tells `format-patch` to output "v2" patches. For instance,
+you may notice that your v2 patches, are all named like
+`v2-000n-my-commit-subject.patch`. `-v2` will also format your patches by
+prefixing them with "[PATCH V2]" instead of "[PATCH]", and your range-diff will
+be prefaced with "Range-diff against v1".
+
+Afer you run this command, `format-patch` will output the patches to the `psuh/`
+directory, alongside the v1 patches. Using a single directory makes it easy to
+refer to the old v1 patches while proofreading the v2 patches, but you will need
+to be careful to send out only the v2 patches. We will use a pattern like
+"psuh/v2-*.patch" ("psuh/*.patch" would match v1 and v2 patches).
 
 Edit your cover letter again. Now is a good time to mention what's different
 between your last version and now, if it's something significant. You do not
@@ -1082,7 +1101,7 @@ to the command:
 ----
 $ git send-email --to=target@example.com
 		 --in-reply-to="<foo.12345.author@example.com>"
-		 psuh/v2*
+		 psuh/v2-*.patch
 ----
 
 [[single-patch]]

-- 
2.33.0.464.g1972c5931b-goog
Eric Sunshine· Sep 21, 2021, 04:59 UTC · re: Glen Choo · lore

Re: [PATCH v2] MyFirstContribution: Document --range-diff option when writing v2

On Mon, Sep 20, 2021 at 10:22 PM Glen Choo <chooglen@google.com> wrote:
Show 15 quoted lines
> In the "Sending v2" section, readers are directed to create v2 patches
> without using --range-diff. However, it is customary to include a
> range-diff against the v1 patches as a reviewer aid.
>
> Update the "Sending v2" section to suggest a simple workflow that uses
> the --range-diff option. Also include some explanation for -v2 and
> --range-diff to help the reader understand the importance.
>
> Signed-off-by: Glen Choo <chooglen@google.com>
> ---
> diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
> @@ -1029,22 +1029,41 @@ kidding - be patient!)
> +Make your changes with `git rebase -i`. Once you're ready with the next
> +iteration of your patch, the process is fairly similar to before. Generate your
> +patches again, but with some new flags:

I wonder if "Make your changes with `git rebase -i`" is a bit too terse for newcomers to understand. Perhaps a bit more verbose:

    Refine your patch series by using `git rebase -i` to adjust
    commits based upon reviewer comments. Once the patch series is
    ready for submission, generate your patches again, but with some
    new flags:
Show 7 quoted lines
>  ----
> +$ git format-patch -v2 --cover-letter -o psuh/ --range-diff master..psuh-v1 master..
>  ----
>
> +The `--range-diff master..psuh-v1` parameter tells `format-patch` to include a
> +range-diff between `psuh-v1` and `psuh` (see linkgit:git-range-diff[1]). This
> +helps tell reviewers about the differences between your v1 and v2 patches.
This leaves dangling the question of where the range-diff is placed. Maybe say:
    ... tells `format-patch` to include a range-diff between ... in
    the cover letter.
Show 5 quoted lines
> +The `-v2` parameter tells `format-patch` to output "v2" patches. For instance,
> +you may notice that your v2 patches, are all named like
> +`v2-000n-my-commit-subject.patch`. `-v2` will also format your patches by
> +prefixing them with "[PATCH V2]" instead of "[PATCH]", and your range-diff will
> +be prefaced with "Range-diff against v1".
s/V2/v2/
Show 5 quoted lines
> +Afer you run this command, `format-patch` will output the patches to the `psuh/`
> +directory, alongside the v1 patches. Using a single directory makes it easy to
> +refer to the old v1 patches while proofreading the v2 patches, but you will need
> +to be careful to send out only the v2 patches. We will use a pattern like
> +"psuh/v2-*.patch" ("psuh/*.patch" would match v1 and v2 patches).
To avoid any sort of confusion, perhaps:
    ... "psuh/v2-*.patch" (not "psuh/*.patch" which would match v1 and
    v2 patches)
Glen Choo· Sep 21, 2021, 17:31 UTC · re: Eric Sunshine · lore

Re: [PATCH v2] MyFirstContribution: Document --range-diff option when writing v2

Eric Sunshine <sunshine@sunshineco.com> writes:
Show 12 quoted lines
>> +Make your changes with `git rebase -i`. Once you're ready with the next
>> +iteration of your patch, the process is fairly similar to before. Generate your
>> +patches again, but with some new flags:
>
> I wonder if "Make your changes with `git rebase -i`" is a bit too
> terse for newcomers to understand. Perhaps a bit more verbose:
>
>     Refine your patch series by using `git rebase -i` to adjust
>     commits based upon reviewer comments. Once the patch series is
>     ready for submission, generate your patches again, but with some
>     new flags:
>

I like your wording :) It seems "obvious" that one should incorporate reviewer comments, but your phrasing makes it that much clearer.

Show 9 quoted lines
>> +The `--range-diff master..psuh-v1` parameter tells `format-patch` to include a
>> +range-diff between `psuh-v1` and `psuh` (see linkgit:git-range-diff[1]). This
>> +helps tell reviewers about the differences between your v1 and v2 patches.
>
> This leaves dangling the question of where the range-diff is placed. Maybe say:
>
>     ... tells `format-patch` to include a range-diff between ... in
>     the cover letter.
>
Sounds good.
Show 7 quoted lines
>> +The `-v2` parameter tells `format-patch` to output "v2" patches. For instance,
>> +you may notice that your v2 patches, are all named like
>> +`v2-000n-my-commit-subject.patch`. `-v2` will also format your patches by
>> +prefixing them with "[PATCH V2]" instead of "[PATCH]", and your range-diff will
>> +be prefaced with "Range-diff against v1".
>
> s/V2/v2/
Thanks!
Show 10 quoted lines
>> +Afer you run this command, `format-patch` will output the patches to the `psuh/`
>> +directory, alongside the v1 patches. Using a single directory makes it easy to
>> +refer to the old v1 patches while proofreading the v2 patches, but you will need
>> +to be careful to send out only the v2 patches. We will use a pattern like
>> +"psuh/v2-*.patch" ("psuh/*.patch" would match v1 and v2 patches).
>
> To avoid any sort of confusion, perhaps:
>
>     ... "psuh/v2-*.patch" (not "psuh/*.patch" which would match v1 and
>     v2 patches)
Agree that making this explicit is a good idea.
Glen Choo· Sep 21, 2021, 17:33 UTC · re: Eric Sunshine · lore

Re: [PATCH v2] MyFirstContribution: Document --range-diff option when writing v2

Eric Sunshine <sunshine@sunshineco.com> writes:
Show 12 quoted lines
>> +Make your changes with `git rebase -i`. Once you're ready with the next
>> +iteration of your patch, the process is fairly similar to before. Generate your
>> +patches again, but with some new flags:
>
> I wonder if "Make your changes with `git rebase -i`" is a bit too
> terse for newcomers to understand. Perhaps a bit more verbose:
>
>     Refine your patch series by using `git rebase -i` to adjust
>     commits based upon reviewer comments. Once the patch series is
>     ready for submission, generate your patches again, but with some
>     new flags:
>

I like your wording :) It seems "obvious" that one should incorporate reviewer comments, but your phrasing makes it that much clearer.

Show 9 quoted lines
>> +The `--range-diff master..psuh-v1` parameter tells `format-patch` to include a
>> +range-diff between `psuh-v1` and `psuh` (see linkgit:git-range-diff[1]). This
>> +helps tell reviewers about the differences between your v1 and v2 patches.
>
> This leaves dangling the question of where the range-diff is placed. Maybe say:
>
>     ... tells `format-patch` to include a range-diff between ... in
>     the cover letter.
>
Sounds good.
Show 7 quoted lines
>> +The `-v2` parameter tells `format-patch` to output "v2" patches. For instance,
>> +you may notice that your v2 patches, are all named like
>> +`v2-000n-my-commit-subject.patch`. `-v2` will also format your patches by
>> +prefixing them with "[PATCH V2]" instead of "[PATCH]", and your range-diff will
>> +be prefaced with "Range-diff against v1".
>
> s/V2/v2/
Thanks!
Show 10 quoted lines
>> +Afer you run this command, `format-patch` will output the patches to the `psuh/`
>> +directory, alongside the v1 patches. Using a single directory makes it easy to
>> +refer to the old v1 patches while proofreading the v2 patches, but you will need
>> +to be careful to send out only the v2 patches. We will use a pattern like
>> +"psuh/v2-*.patch" ("psuh/*.patch" would match v1 and v2 patches).
>
> To avoid any sort of confusion, perhaps:
>
>     ... "psuh/v2-*.patch" (not "psuh/*.patch" which would match v1 and
>     v2 patches)
Agree that making this explicit is a good idea.
Glen Choo· Sep 21, 2021, 17:34 UTC · re: Eric Sunshine · lore

Re: [PATCH v2] MyFirstContribution: Document --range-diff option when writing v2

Eric Sunshine <sunshine@sunshineco.com> writes:
Show 12 quoted lines
>> +Make your changes with `git rebase -i`. Once you're ready with the next
>> +iteration of your patch, the process is fairly similar to before. Generate your
>> +patches again, but with some new flags:
>
> I wonder if "Make your changes with `git rebase -i`" is a bit too
> terse for newcomers to understand. Perhaps a bit more verbose:
>
>     Refine your patch series by using `git rebase -i` to adjust
>     commits based upon reviewer comments. Once the patch series is
>     ready for submission, generate your patches again, but with some
>     new flags:
>

I like your wording :) It seems "obvious" that one should incorporate reviewer comments, but your phrasing makes it that much clearer.

Show 9 quoted lines
>> +The `--range-diff master..psuh-v1` parameter tells `format-patch` to include a
>> +range-diff between `psuh-v1` and `psuh` (see linkgit:git-range-diff[1]). This
>> +helps tell reviewers about the differences between your v1 and v2 patches.
>
> This leaves dangling the question of where the range-diff is placed. Maybe say:
>
>     ... tells `format-patch` to include a range-diff between ... in
>     the cover letter.
>
Sounds good.
Show 7 quoted lines
>> +The `-v2` parameter tells `format-patch` to output "v2" patches. For instance,
>> +you may notice that your v2 patches, are all named like
>> +`v2-000n-my-commit-subject.patch`. `-v2` will also format your patches by
>> +prefixing them with "[PATCH V2]" instead of "[PATCH]", and your range-diff will
>> +be prefaced with "Range-diff against v1".
>
> s/V2/v2/
Thanks!
Show 10 quoted lines
>> +Afer you run this command, `format-patch` will output the patches to the `psuh/`
>> +directory, alongside the v1 patches. Using a single directory makes it easy to
>> +refer to the old v1 patches while proofreading the v2 patches, but you will need
>> +to be careful to send out only the v2 patches. We will use a pattern like
>> +"psuh/v2-*.patch" ("psuh/*.patch" would match v1 and v2 patches).
>
> To avoid any sort of confusion, perhaps:
>
>     ... "psuh/v2-*.patch" (not "psuh/*.patch" which would match v1 and
>     v2 patches)
Agree that making this explicit is a good idea.
Bagas Sanjaya· Sep 21, 2021, 05:33 UTC · re: Glen Choo · lore

Re: [PATCH v2] MyFirstContribution: Document --range-diff option when writing v2

On 21/09/21 05.32, Glen Choo wrote:
Show 17 quoted lines
> -Skip ahead to <<reviewing,Responding to Reviews>> for information on how to
> -handle comments from reviewers. Continue this section when your topic branch is
> -shaped the way you want it to look for your patchset v2.
> +This section will focus on how to send a v2 of your patchset. To learn what
> +should go into v2, skip ahead to <<reviewing,Responding to Reviews>> for
> +information on how to handle comments from reviewers.
> +
> +We'll reuse our `psuh` topic branch for v2. Before we make any changes, we'll
> +mark the tip of our v1 branch for easy reference:
>   
> -When you're ready with the next iteration of your patch, the process is fairly
> -similar.
> +----
> +$ git checkout psuh
> +$ git branch psuh-v1
> +----
>

Alternatively we can branch off psuh-v2 from the original psuh: ---- $ git checkout psuh $ git checkout -b psuh-v2 ----

The original psuh thus become v1. To easily identify it, we can run: ---- $ git checkout psuh $ git branch -M psuh-v1 ----

Show 5 quoted lines
> -First, generate your v2 patches again:
> +Make your changes with `git rebase -i`. Once you're ready with the next
> +iteration of your patch, the process is fairly similar to before. Generate your
> +patches again, but with some new flags:
>

For completeness, we can say "Make your changes with `git rebase -i`. Actions that you have to select in the todo editor of rebase depend on reviewers' comments. For example, if they asked to squash a commit into previous one, say `pick` on the latter and `squash` on the former."

Show 18 quoted lines
>   ----
> -$ git format-patch -v2 --cover-letter -o psuh/ master..psuh
> +$ git format-patch -v2 --cover-letter -o psuh/ --range-diff master..psuh-v1 master..
>   ----
>   
> -This will add your v2 patches, all named like `v2-000n-my-commit-subject.patch`,
> -to the `psuh/` directory. You may notice that they are sitting alongside the v1
> -patches; that's fine, but be careful when you are ready to send them.
> +The `--range-diff master..psuh-v1` parameter tells `format-patch` to include a
> +range-diff between `psuh-v1` and `psuh` (see linkgit:git-range-diff[1]). This
> +helps tell reviewers about the differences between your v1 and v2 patches.
> +
> +The `-v2` parameter tells `format-patch` to output "v2" patches. For instance,
> +you may notice that your v2 patches, are all named like
> +`v2-000n-my-commit-subject.patch`. `-v2` will also format your patches by
> +prefixing them with "[PATCH V2]" instead of "[PATCH]", and your range-diff will
> +be prefaced with "Range-diff against v1".
> +
More accurately, `-v 2` marks the patchset as second iteration of it.
Show 18 quoted lines
> +Afer you run this command, `format-patch` will output the patches to the `psuh/`
> +directory, alongside the v1 patches. Using a single directory makes it easy to
> +refer to the old v1 patches while proofreading the v2 patches, but you will need
> +to be careful to send out only the v2 patches. We will use a pattern like
> +"psuh/v2-*.patch" ("psuh/*.patch" would match v1 and v2 patches).
>   
>   Edit your cover letter again. Now is a good time to mention what's different
>   between your last version and now, if it's something significant. You do not
> @@ -1082,7 +1101,7 @@ to the command:
>   ----
>   $ git send-email --to=target@example.com
>   		 --in-reply-to="<foo.12345.author@example.com>"
> -		 psuh/v2*
> +		 psuh/v2-*.patch
>   ----
>   
>   [[single-patch]]
> 
-- 
An old man doll... just what I always wanted! - Clara
Glen Choo· Sep 21, 2021, 17:58 UTC · re: Bagas Sanjaya · lore

Re: [PATCH v2] MyFirstContribution: Document --range-diff option when writing v2

Bagas Sanjaya <bagasdotme@gmail.com> writes:
Show 23 quoted lines
>> +We'll reuse our `psuh` topic branch for v2. Before we make any changes, we'll
>> +mark the tip of our v1 branch for easy reference:
>>   
>> -When you're ready with the next iteration of your patch, the process is fairly
>> -similar.
>> +----
>> +$ git checkout psuh
>> +$ git branch psuh-v1
>> +----
>>   
>
> Alternatively we can branch off psuh-v2 from the original psuh:
> ----
> $ git checkout psuh
> $ git checkout -b psuh-v2
> ----
>
> The original psuh thus become v1. To easily identify it, we can run:
> ----
> $ git checkout psuh
> $ git branch -M psuh-v1
> ----
>
I proposed to reuse the topic branch at the suggestion of Junio.
 I do not think it is a good suggestion at all to use a new topic
 branch, especially a one that forked from the tip of the original
 submission, and work on that branch to produce the new round.  It
 would be much better to create a topic branch or a lightweight tag
 "psuh-v1" that points at the old tip and keep working on the same
 branch.  But that is a separate story.

Your suggested workflow is acutally fairly similar to the one I actually use. To keep this doc clear though, I think that we should probably propose just one workflow.

Show 5 quoted lines
> For completeness, we can say "Make your changes with `git rebase -i`. 
> Actions that you have to select in the todo editor of rebase depend on 
> reviewers' comments. For example, if they asked to squash a commit into 
> previous one, say `pick` on the latter and `squash` on the former."
>

I hesitate to add a "rebase -i" tutorial because this document doesn't contain similar tutorials/explanations for any 'regular' Git workflow commands; the explanations are generally focused on mailing list-specific commands like "send-email" and "format-patch".

It seems unlikely to me that an aspiring contributor to Git would be unfamiliar with "rebase -i". It's not the most simple command, but it is common. In fact, because it is not so simple, it seems unlikely that we would do it justice in this document. For those who need it, additional reading on "rebase -i" can be left as an exercise to the reader.

>> +The `-v2` parameter tells `format-patch` to output "v2" patches. For instance,
>
> More accurately, `-v 2` marks the patchset as second iteration of it.
>

Good point. I was stuggling with how to word this paragraph. I'll work that wording into this line.

Junio C Hamano· Sep 22, 2021, 18:54 UTC · re: Bagas Sanjaya · lore

Re: [PATCH v2] MyFirstContribution: Document --range-diff option when writing v2

Bagas Sanjaya <bagasdotme@gmail.com> writes:
Show 11 quoted lines
>> +----
>> +$ git checkout psuh
>> +$ git branch psuh-v1
>> +----
>>   
>
> Alternatively we can branch off psuh-v2 from the original psuh:
> ----
> $ git checkout psuh
> $ git checkout -b psuh-v2
> ----

It would lose the continuity in "git reflog @{now}" while continuing to work on the psuh feature. So it may be an "alternative", but I do not think why anybody wants to recommend ti as an alternative when "tag the end of the v1 iteration and keep using the same" was already given. If the original said "stop working on psuh and start a new branch called psuh-v2", and then "no, mark the notable point and keep using the same" is offered as an alternative, it might be worth sending a message about, though.

Philip Oakley· Sep 22, 2021, 12:18 UTC · re: Glen Choo · lore

Re: [PATCH v2] MyFirstContribution: Document --range-diff option when writing v2

On 20/09/2021 23:32, Glen Choo wrote:
Show 148 quoted lines
> In the "Sending v2" section, readers are directed to create v2 patches
> without using --range-diff. However, it is customary to include a
> range-diff against the v1 patches as a reviewer aid.
>
> Update the "Sending v2" section to suggest a simple workflow that uses
> the --range-diff option. Also include some explanation for -v2 and
> --range-diff to help the reader understand the importance.
>
> Signed-off-by: Glen Choo <chooglen@google.com>
> ---
> Thanks for the helpful comments on v1! v2 aims to clear up other
> ambiguities from v1 and to propose a specific workflow for readers.
>
> Changes since v1:
>
> * recommend that readers reuse the `psuh` topic branch for v2
> * recommend that readers mark their v1 topic branch
> * add a link to the range-diff docs
> * change the v2 glob pattern to `psuh/v2-*.patch` to match the v1 example
> * explicitly call out the v2 glob pattern so that readers will be extra
>   careful
>
> Interdiff against v1:
>   diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
>   index add1c2bba9..790bf1e8b5 100644
>   --- a/Documentation/MyFirstContribution.txt
>   +++ b/Documentation/MyFirstContribution.txt
>   @@ -1029,27 +1029,29 @@ kidding - be patient!)
>    [[v2-git-send-email]]
>    === Sending v2
>    
>   -Skip ahead to <<reviewing,Responding to Reviews>> for information on how to
>   -handle comments from reviewers. Continue this section when your topic branch is
>   -shaped the way you want it to look for your patchset v2.
>   +This section will focus on how to send a v2 of your patchset. To learn what
>   +should go into v2, skip ahead to <<reviewing,Responding to Reviews>> for
>   +information on how to handle comments from reviewers.
>    
>   -Let's write v2 as its own topic branch, because this will make some things more
>   -convenient later on. Create the `psuh-v2` branch like so:
>   +We'll reuse our `psuh` topic branch for v2. Before we make any changes, we'll
>   +mark the tip of our v1 branch for easy reference:
>    
>    ----
>   -$ git checkout -b psuh-v2 psuh
>   +$ git checkout psuh
>   +$ git branch psuh-v1
>    ----
>    
>   -When you're ready with the next iteration of your patch, the process is fairly
>   -similar to before. Generate your patches again, but with some new flags:
>   +Make your changes with `git rebase -i`. Once you're ready with the next
>   +iteration of your patch, the process is fairly similar to before. Generate your
>   +patches again, but with some new flags:
>    
>    ----
>   -$ git format-patch -v2 --range-diff psuh..psuh-v2 --cover-letter -o psuh/ master..psuh
>   +$ git format-patch -v2 --cover-letter -o psuh/ --range-diff master..psuh-v1 master..
>    ----
>    
>   -The `--range-diff psuh..psuh-v2` parameter tells `format-patch` to include a
>   -range diff between `psuh` and `psuh-v2`. This helps tell reviewers about the
>   -differences between your v1 and v2 patches.
>   +The `--range-diff master..psuh-v1` parameter tells `format-patch` to include a
>   +range-diff between `psuh-v1` and `psuh` (see linkgit:git-range-diff[1]). This
>   +helps tell reviewers about the differences between your v1 and v2 patches.
>    
>    The `-v2` parameter tells `format-patch` to output "v2" patches. For instance,
>    you may notice that your v2 patches, are all named like
>   @@ -1058,8 +1060,10 @@ prefixing them with "[PATCH V2]" instead of "[PATCH]", and your range-diff will
>    be prefaced with "Range-diff against v1".
>    
>    Afer you run this command, `format-patch` will output the patches to the `psuh/`
>   -directory, alongside the v1 patches. That's fine, but be careful when you are
>   -ready to send them.
>   +directory, alongside the v1 patches. Using a single directory makes it easy to
>   +refer to the old v1 patches while proofreading the v2 patches, but you will need
>   +to be careful to send out only the v2 patches. We will use a pattern like
>   +"psuh/v2-*.patch" ("psuh/*.patch" would match v1 and v2 patches).
>    
>    Edit your cover letter again. Now is a good time to mention what's different
>    between your last version and now, if it's something significant. You do not
>   @@ -1097,7 +1101,7 @@ to the command:
>    ----
>    $ git send-email --to=target@example.com
>    		 --in-reply-to="<foo.12345.author@example.com>"
>   -		 psuh/v2*
>   +		 psuh/v2-*.patch
>    ----
>    
>    [[single-patch]]
>
>  Documentation/MyFirstContribution.txt | 41 ++++++++++++++++++++-------
>  1 file changed, 30 insertions(+), 11 deletions(-)
>
> diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
> index 015cf24631..790bf1e8b5 100644
> --- a/Documentation/MyFirstContribution.txt
> +++ b/Documentation/MyFirstContribution.txt
> @@ -1029,22 +1029,41 @@ kidding - be patient!)
>  [[v2-git-send-email]]
>  === Sending v2
>  
> -Skip ahead to <<reviewing,Responding to Reviews>> for information on how to
> -handle comments from reviewers. Continue this section when your topic branch is
> -shaped the way you want it to look for your patchset v2.
> +This section will focus on how to send a v2 of your patchset. To learn what
> +should go into v2, skip ahead to <<reviewing,Responding to Reviews>> for
> +information on how to handle comments from reviewers.
> +
> +We'll reuse our `psuh` topic branch for v2. Before we make any changes, we'll
> +mark the tip of our v1 branch for easy reference:
>  
> -When you're ready with the next iteration of your patch, the process is fairly
> -similar.
> +----
> +$ git checkout psuh
> +$ git branch psuh-v1
> +----
>  
> -First, generate your v2 patches again:
> +Make your changes with `git rebase -i`. Once you're ready with the next
> +iteration of your patch, the process is fairly similar to before. Generate your
> +patches again, but with some new flags:
>  
>  ----
> -$ git format-patch -v2 --cover-letter -o psuh/ master..psuh
> +$ git format-patch -v2 --cover-letter -o psuh/ --range-diff master..psuh-v1 master..
>  ----
>  
> -This will add your v2 patches, all named like `v2-000n-my-commit-subject.patch`,
> -to the `psuh/` directory. You may notice that they are sitting alongside the v1
> -patches; that's fine, but be careful when you are ready to send them.
> +The `--range-diff master..psuh-v1` parameter tells `format-patch` to include a
> +range-diff between `psuh-v1` and `psuh` (see linkgit:git-range-diff[1]). This
> +helps tell reviewers about the differences between your v1 and v2 patches.
> +
> +The `-v2` parameter tells `format-patch` to output "v2" patches. For instance,
> +you may notice that your v2 patches, are all named like
> +`v2-000n-my-commit-subject.patch`. `-v2` will also format your patches by
> +prefixing them with "[PATCH V2]" instead of "[PATCH]", and your range-diff will
> +be prefaced with "Range-diff against v1".
> +
> +Afer you run this command, `format-patch` will output the patches to the `psuh/`
> +directory, alongside the v1 patches. Using a single directory makes it easy to
> +refer to the old v1 patches while proofreading the v2 patches, but you will need
> +to be careful to send out only the v2 patches. We will use a pattern like
> +"psuh/v2-*.patch" ("psuh/*.patch" would match v1 and v2 patches).

Do we need a line to cover/suggest how the V2 to V3 follow up to further review commands are tweaked.

This sort of follows from the discussion about keeping the branch `psuh` as the working branch, and the `-v1`, -`v2`, `-v3` as the record of former submissions. The range-diff is then tweaked to be `--range-diff master..psuh-v<N>` where N is the last proper submission (just in case one version was a not-submitted dud).

(Hmm. Writing that was useful to help clear my thoughts as well ;-)
Thanks for working on this.
-- 
Philip
>  
>  Edit your cover letter again. Now is a good time to mention what's different
>  between your last version and now, if it's something significant. You do not
> @@ -1082,7 +1101,7 @@ to the command:
>  ----
>  $ git send-email --to=target@example.com
>  		 --in-reply-to="<foo.12345.author@example.com>"
> -		 psuh/v2*
> +		 psuh/v2-*.patch
>  ----
>  
>  [[single-patch]]
Glen Choo· Sep 22, 2021, 17:34 UTC · re: Philip Oakley · lore

Re: [PATCH v2] MyFirstContribution: Document --range-diff option when writing v2

Philip Oakley <philipoakley@iee.email> writes:
Show 8 quoted lines
> Do we need a line to cover/suggest how the V2 to V3 follow up to further
> review commands are tweaked.
>
> This sort of follows from the discussion about keeping the branch `psuh`
> as the working branch, and the `-v1`, -`v2`, `-v3` as the record of
> former submissions. The range-diff is then tweaked to be `--range-diff
> master..psuh-v<N>` where N is the last proper submission (just in case
> one version was a not-submitted dud).

While writing, it seemed pretty obvious to me that v2 -> v3 would just entail adding 1 to every numeral. Of course I'm biased though, so I'm happy to add a line if you think this isn't that obvious.

Philip Oakley· Sep 23, 2021, 13:44 UTC · re: Glen Choo · lore

Re: [PATCH v2] MyFirstContribution: Document --range-diff option when writing v2

On 22/09/2021 18:34, Glen Choo wrote:
Show 13 quoted lines
> Philip Oakley <philipoakley@iee.email> writes:
>
>> Do we need a line to cover/suggest how the V2 to V3 follow up to further
>> review commands are tweaked.
>>
>> This sort of follows from the discussion about keeping the branch `psuh`
>> as the working branch, and the `-v1`, -`v2`, `-v3` as the record of
>> former submissions. The range-diff is then tweaked to be `--range-diff
>> master..psuh-v<N>` where N is the last proper submission (just in case
>> one version was a not-submitted dud).
> While writing, it seemed pretty obvious to me that v2 -> v3 would just
> entail adding 1 to every numeral. Of course I'm biased though, so I'm
> happy to add a line if you think this isn't that obvious.

I'd been coming from thinking of the `range-diff` command where a second range would be required, with a flipping of the grandfather - father - son version references, part triggered by the (false) expectation that the `master..` would also need tweaked.

It's is hard in ref manuals to decide the point at which one need to either give guidance, or point out common conceptual errors.

Also, separately, it may be worth commenting (or just mentioning) about whether to keep the fork-point (or --keep-base) or not, depending on the complexity of the patch series and how it may clash with other series (making it harder for the maintainer if the `rerere` database would need to keep changing)....

All in all. I think we (I) are good with your wording.
Philip
Bagas Sanjaya· Sep 23, 2021, 05:46 UTC · re: Philip Oakley · lore

Re: [PATCH v2] MyFirstContribution: Document --range-diff option when writing v2

On 22/09/21 19.18, Philip Oakley wrote:
Show 8 quoted lines
> Do we need a line to cover/suggest how the V2 to V3 follow up to further
> review commands are tweaked.
> 
> This sort of follows from the discussion about keeping the branch `psuh`
> as the working branch, and the `-v1`, -`v2`, `-v3` as the record of
> former submissions. The range-diff is then tweaked to be `--range-diff
> master..psuh-v<N>` where N is the last proper submission (just in case
> one version was a not-submitted dud).
Yes, the process is similar to v2.
-- 
An old man doll... just what I always wanted! - Clara
Glen Choo· Sep 22, 2021, 20:22 UTC · re: Glen Choo · lore

[PATCH v3] MyFirstContribution: Document --range-diff option when writing v2

In the "Sending v2" section, readers are directed to create v2 patches without using --range-diff. However, it is customary to include a range-diff against the v1 patches as a reviewer aid.

Update the "Sending v2" section to suggest a simple workflow that uses the --range-diff option. Also include some explanation for -v2 and --range-diff to help the reader understand the importance.

Signed-off-by: Glen Choo <chooglen@google.com>
---
This tightens up some of the language from v2, but is otherwise largely
similar. As always, thanks for the input!
Changes since v2:
* clarify that the range-diff is inserted into the cover letter
* describe -v2 as creating version "2" instead of "v2"
* fix typo in email prefix (s/V2/v2)
* explicitly compare the v2 glob pattern with the v1 glob pattern
Interdiff against v2:
  diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
  index 790bf1e8b5..b20bc8e914 100644
  --- a/Documentation/MyFirstContribution.txt
  +++ b/Documentation/MyFirstContribution.txt
  @@ -1041,8 +1041,8 @@ $ git checkout psuh
   $ git branch psuh-v1
   ----
   
  -Make your changes with `git rebase -i`. Once you're ready with the next
  -iteration of your patch, the process is fairly similar to before. Generate your
  +Refine your patch series by using `git rebase -i` to adjust commits based upon
  +reviewer comments. Once the patch series is ready for submission, generate your
   patches again, but with some new flags:
   
   ----
  @@ -1050,20 +1050,21 @@ $ git format-patch -v2 --cover-letter -o psuh/ --range-diff master..psuh-v1 mast
   ----
   
   The `--range-diff master..psuh-v1` parameter tells `format-patch` to include a
  -range-diff between `psuh-v1` and `psuh` (see linkgit:git-range-diff[1]). This
  -helps tell reviewers about the differences between your v1 and v2 patches.
  +range-diff between `psuh-v1` and `psuh` in the cover letter (see
  +linkgit:git-range-diff[1]). This helps tell reviewers about the differences
  +between your v1 and v2 patches.
   
  -The `-v2` parameter tells `format-patch` to output "v2" patches. For instance,
  -you may notice that your v2 patches, are all named like
  -`v2-000n-my-commit-subject.patch`. `-v2` will also format your patches by
  -prefixing them with "[PATCH V2]" instead of "[PATCH]", and your range-diff will
  -be prefaced with "Range-diff against v1".
  +The `-v2` parameter tells `format-patch` to output your patches
  +as version "2". For instance, you may notice that your v2 patches are
  +all named like `v2-000n-my-commit-subject.patch`. `-v2` will also format
  +your patches by prefixing them with "[PATCH v2]" instead of "[PATCH]",
  +and your range-diff will be prefaced with "Range-diff against v1".
   
   Afer you run this command, `format-patch` will output the patches to the `psuh/`
   directory, alongside the v1 patches. Using a single directory makes it easy to
   refer to the old v1 patches while proofreading the v2 patches, but you will need
   to be careful to send out only the v2 patches. We will use a pattern like
  -"psuh/v2-*.patch" ("psuh/*.patch" would match v1 and v2 patches).
  +"psuh/v2-*.patch" (not "psuh/*.patch", which would match v1 and v2 patches).
   
   Edit your cover letter again. Now is a good time to mention what's different
   between your last version and now, if it's something significant. You do not
 Documentation/MyFirstContribution.txt | 42 ++++++++++++++++++++-------
 1 file changed, 31 insertions(+), 11 deletions(-)
Show changes to Documentation/MyFirstContribution.txt +31 −11
diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
index 015cf24631..b20bc8e914 100644
--- a/Documentation/MyFirstContribution.txt
+++ b/Documentation/MyFirstContribution.txt
@@ -1029,22 +1029,42 @@ kidding - be patient!)
 [[v2-git-send-email]]
 === Sending v2
 
-Skip ahead to <<reviewing,Responding to Reviews>> for information on how to
-handle comments from reviewers. Continue this section when your topic branch is
-shaped the way you want it to look for your patchset v2.
+This section will focus on how to send a v2 of your patchset. To learn what
+should go into v2, skip ahead to <<reviewing,Responding to Reviews>> for
+information on how to handle comments from reviewers.
+
+We'll reuse our `psuh` topic branch for v2. Before we make any changes, we'll
+mark the tip of our v1 branch for easy reference:
 
-When you're ready with the next iteration of your patch, the process is fairly
-similar.
+----
+$ git checkout psuh
+$ git branch psuh-v1
+----
 
-First, generate your v2 patches again:
+Refine your patch series by using `git rebase -i` to adjust commits based upon
+reviewer comments. Once the patch series is ready for submission, generate your
+patches again, but with some new flags:
 
 ----
-$ git format-patch -v2 --cover-letter -o psuh/ master..psuh
+$ git format-patch -v2 --cover-letter -o psuh/ --range-diff master..psuh-v1 master..
 ----
 
-This will add your v2 patches, all named like `v2-000n-my-commit-subject.patch`,
-to the `psuh/` directory. You may notice that they are sitting alongside the v1
-patches; that's fine, but be careful when you are ready to send them.
+The `--range-diff master..psuh-v1` parameter tells `format-patch` to include a
+range-diff between `psuh-v1` and `psuh` in the cover letter (see
+linkgit:git-range-diff[1]). This helps tell reviewers about the differences
+between your v1 and v2 patches.
+
+The `-v2` parameter tells `format-patch` to output your patches
+as version "2". For instance, you may notice that your v2 patches are
+all named like `v2-000n-my-commit-subject.patch`. `-v2` will also format
+your patches by prefixing them with "[PATCH v2]" instead of "[PATCH]",
+and your range-diff will be prefaced with "Range-diff against v1".
+
+Afer you run this command, `format-patch` will output the patches to the `psuh/`
+directory, alongside the v1 patches. Using a single directory makes it easy to
+refer to the old v1 patches while proofreading the v2 patches, but you will need
+to be careful to send out only the v2 patches. We will use a pattern like
+"psuh/v2-*.patch" (not "psuh/*.patch", which would match v1 and v2 patches).
 
 Edit your cover letter again. Now is a good time to mention what's different
 between your last version and now, if it's something significant. You do not
@@ -1082,7 +1102,7 @@ to the command:
 ----
 $ git send-email --to=target@example.com
 		 --in-reply-to="<foo.12345.author@example.com>"
-		 psuh/v2*
+		 psuh/v2-*.patch
 ----
 
 [[single-patch]]

-- 
2.33.0.464.g1972c5931b-goog

← back to recent threads