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

From: Junio C Hamano <gitster@pobox.com>
Date: Sep 14, 2021, 21:39 UTC
Message-ID: <xmqq7dfizvjt.fsf@gitster.g>
In-Reply-To: <YUDaIc19rhendwc9@chooglen-macbookpro.roam.corp.google.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).

Show 5 quoted lines

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