* Re: [PATCH v2] MyFirstContribution: Document --range-diff option when writing v2
2021-09-20 22:32 ` [PATCH v2] " Glen Choo
@ 2021-09-21 4:59 ` Eric Sunshine
2021-09-21 17:31 ` Glen Choo
` (2 more replies)
2021-09-21 5:33 ` Bagas Sanjaya
` (2 subsequent siblings)
3 siblings, 3 replies; 22+ messages in thread
From: Eric Sunshine @ 2021-09-21 4:59 UTC (permalink / raw)
To: Glen Choo; +Cc: Git List
On Mon, Sep 20, 2021 at 10:22 PM Glen Choo <chooglen@google.com> wrote:
> 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:
> ----
> +$ 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.
> +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/
> +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)
^ permalink raw reply [flat|nested] 22+ messages in thread
* Re: [PATCH v2] MyFirstContribution: Document --range-diff option when writing v2
2021-09-21 4:59 ` Eric Sunshine
@ 2021-09-21 17:31 ` Glen Choo
2021-09-21 17:33 ` Glen Choo
2021-09-21 17:34 ` Glen Choo
2 siblings, 0 replies; 22+ messages in thread
From: Glen Choo @ 2021-09-21 17:31 UTC (permalink / raw)
To: Eric Sunshine; +Cc: Git List
Eric Sunshine <sunshine@sunshineco.com> writes:
>> +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.
>> +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.
>> +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!
>> +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.
^ permalink raw reply [flat|nested] 22+ messages in thread
* Re: [PATCH v2] MyFirstContribution: Document --range-diff option when writing v2
2021-09-21 4:59 ` Eric Sunshine
2021-09-21 17:31 ` Glen Choo
@ 2021-09-21 17:33 ` Glen Choo
2021-09-21 17:34 ` Glen Choo
2 siblings, 0 replies; 22+ messages in thread
From: Glen Choo @ 2021-09-21 17:33 UTC (permalink / raw)
To: Eric Sunshine; +Cc: Git List
Eric Sunshine <sunshine@sunshineco.com> writes:
>> +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.
>> +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.
>> +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!
>> +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.
^ permalink raw reply [flat|nested] 22+ messages in thread
* Re: [PATCH v2] MyFirstContribution: Document --range-diff option when writing v2
2021-09-21 4:59 ` Eric Sunshine
2021-09-21 17:31 ` Glen Choo
2021-09-21 17:33 ` Glen Choo
@ 2021-09-21 17:34 ` Glen Choo
2 siblings, 0 replies; 22+ messages in thread
From: Glen Choo @ 2021-09-21 17:34 UTC (permalink / raw)
To: Eric Sunshine; +Cc: Git List
Eric Sunshine <sunshine@sunshineco.com> writes:
>> +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.
>> +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.
>> +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!
>> +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.
^ permalink raw reply [flat|nested] 22+ messages in thread
* Re: [PATCH v2] MyFirstContribution: Document --range-diff option when writing v2
2021-09-20 22:32 ` [PATCH v2] " Glen Choo
2021-09-21 4:59 ` Eric Sunshine
@ 2021-09-21 5:33 ` Bagas Sanjaya
2021-09-21 17:58 ` Glen Choo
2021-09-22 18:54 ` Junio C Hamano
2021-09-22 12:18 ` Philip Oakley
2021-09-22 20:22 ` [PATCH v3] " Glen Choo
3 siblings, 2 replies; 22+ messages in thread
From: Bagas Sanjaya @ 2021-09-21 5:33 UTC (permalink / raw)
To: Glen Choo, git
On 21/09/21 05.32, Glen Choo wrote:
> -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
----
> -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."
> ----
> -$ 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.
> +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
^ permalink raw reply [flat|nested] 22+ messages in thread
* Re: [PATCH v2] MyFirstContribution: Document --range-diff option when writing v2
2021-09-21 5:33 ` Bagas Sanjaya
@ 2021-09-21 17:58 ` Glen Choo
2021-09-22 18:54 ` Junio C Hamano
1 sibling, 0 replies; 22+ messages in thread
From: Glen Choo @ 2021-09-21 17:58 UTC (permalink / raw)
To: Bagas Sanjaya; +Cc: git
Bagas Sanjaya <bagasdotme@gmail.com> writes:
>> +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.
> 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.
^ permalink raw reply [flat|nested] 22+ messages in thread
* Re: [PATCH v2] MyFirstContribution: Document --range-diff option when writing v2
2021-09-21 5:33 ` Bagas Sanjaya
2021-09-21 17:58 ` Glen Choo
@ 2021-09-22 18:54 ` Junio C Hamano
1 sibling, 0 replies; 22+ messages in thread
From: Junio C Hamano @ 2021-09-22 18:54 UTC (permalink / raw)
To: Bagas Sanjaya; +Cc: Glen Choo, git
Bagas Sanjaya <bagasdotme@gmail.com> writes:
>> +----
>> +$ 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.
^ permalink raw reply [flat|nested] 22+ messages in thread
* Re: [PATCH v2] MyFirstContribution: Document --range-diff option when writing v2
2021-09-20 22:32 ` [PATCH v2] " Glen Choo
2021-09-21 4:59 ` Eric Sunshine
2021-09-21 5:33 ` Bagas Sanjaya
@ 2021-09-22 12:18 ` Philip Oakley
2021-09-22 17:34 ` Glen Choo
2021-09-23 5:46 ` Bagas Sanjaya
2021-09-22 20:22 ` [PATCH v3] " Glen Choo
3 siblings, 2 replies; 22+ messages in thread
From: Philip Oakley @ 2021-09-22 12:18 UTC (permalink / raw)
To: Glen Choo, git
On 20/09/2021 23:32, Glen Choo wrote:
> 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]]
^ permalink raw reply [flat|nested] 22+ messages in thread
* Re: [PATCH v2] MyFirstContribution: Document --range-diff option when writing v2
2021-09-22 12:18 ` Philip Oakley
@ 2021-09-22 17:34 ` Glen Choo
2021-09-23 13:44 ` Philip Oakley
2021-09-23 5:46 ` Bagas Sanjaya
1 sibling, 1 reply; 22+ messages in thread
From: Glen Choo @ 2021-09-22 17:34 UTC (permalink / raw)
To: Philip Oakley, git
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.
^ permalink raw reply [flat|nested] 22+ messages in thread
* Re: [PATCH v2] MyFirstContribution: Document --range-diff option when writing v2
2021-09-22 17:34 ` Glen Choo
@ 2021-09-23 13:44 ` Philip Oakley
0 siblings, 0 replies; 22+ messages in thread
From: Philip Oakley @ 2021-09-23 13:44 UTC (permalink / raw)
To: Glen Choo, git
On 22/09/2021 18:34, Glen Choo wrote:
> 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
^ permalink raw reply [flat|nested] 22+ messages in thread
* Re: [PATCH v2] MyFirstContribution: Document --range-diff option when writing v2
2021-09-22 12:18 ` Philip Oakley
2021-09-22 17:34 ` Glen Choo
@ 2021-09-23 5:46 ` Bagas Sanjaya
1 sibling, 0 replies; 22+ messages in thread
From: Bagas Sanjaya @ 2021-09-23 5:46 UTC (permalink / raw)
To: Philip Oakley, Glen Choo, git
On 22/09/21 19.18, Philip Oakley wrote:
> 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
^ permalink raw reply [flat|nested] 22+ messages in thread
* [PATCH v3] MyFirstContribution: Document --range-diff option when writing v2
2021-09-20 22:32 ` [PATCH v2] " Glen Choo
` (2 preceding siblings ...)
2021-09-22 12:18 ` Philip Oakley
@ 2021-09-22 20:22 ` Glen Choo
3 siblings, 0 replies; 22+ messages in thread
From: Glen Choo @ 2021-09-22 20:22 UTC (permalink / raw)
To: git; +Cc: Glen Choo
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(-)
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
^ permalink raw reply related [flat|nested] 22+ messages in thread