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

[Junio C Hamano <gitster@pobox.com>]

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).

>> 	# ..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.