Re: [PATCH v2] MyFirstContribution: Document --range-diff option when writing v2
- From
Glen Choo <chooglen@google.com>
- Date
- Sep 21, 2021, 17:31 UTC
- Message-ID
- <kl6l4kadn8dg.fsf@chooglen-macbookpro.roam.corp.google.com>
- In-Reply-To
- <CAPig+cR8ZRGVrNsf6nbBsjuLt768fr=SB+bY_bD+tQpkzrL7FA@mail.gmail.com>
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.