| Message ID | 20210920223226.25877-1-chooglen@google.com (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | [v2] MyFirstContribution: Document --range-diff option when writing v2 | expand |
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)
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]] >
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.
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.
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.
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.
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 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.
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.
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.
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
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]]
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(-)