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

[Glen Choo <chooglen@google.com>]

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.