Re: [PATCH v3 0/4] clarify meaning of --signoff & related doc improvements in describing Signed-off-by

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

"Bradley M. Kuhn" <bkuhn@sfconservancy.org> writes:

> I wasn't sure what I should be doing with the patch set once it was already
> in 'seen'.  The only two references in SubmittingPatches I could find were:

Being 'seen' is an indication that it has been seen and does not
mean anything more than that.  It is appreciated that a topic in
such a state is improved by replacing.

> From Documentation/SubmittingPatches:
>>> In any time between the (2)-(3) cycle, the maintainer may pick it up from
>>> the list and queue it to `seen`, in order to make it easier for people
>>> play with it without having to pick up and apply the patch to their trees
>>> themselves.

Yes.  Other people then can "git fetch" from me and follow the first
parent chain "git log --first-parent origin/master..origin/seen" to
find the tip of your topic, instead of finding your message in the
list archive and running "git am" themselves.

The original submitter/owner of the topic can also find the tip of
the topic _in_ my tree the same way as others and reset their branch
to what is queued in 'seen' if they wanted to keep minor fixes I
made based on review comments while applying the e-mailed patches.

Then they can further work on polishing the topic with the usual
means, e.g. using "rebase -i", and finally "format-patch" to send
out a new round.  Being or not being in 'seen' does not change the
workflow that much.

>>> `git pull --rebase` will automatically skip already-applied patches, and
>>> will let you know. This works only if you rebase on top of the branch in
>>> which your patch has been merged (i.e. it will not tell you if your patch
>>> is merged in `seen` if you rebase on top of master).

This is talking about a fairly mature topic that has already been in
'next' and was on the course to graduate to 'master'.  The topic
would eventually be in 'master', and at that point "pull --rebase"
would notice that the patches are no longer needed (or were merged
in a different form).  But that does not apply to topics that are
not in 'master' yet.

Where the workflow changes is when the topic hits 'next'.  After
that, we request you to give incremental updates to refine what is
queued already.  

The reasoning behind this is simple and arbitrary.  It often is the
case that keeping mistakes in early iterations, and fixes to these
mistakes, recorded in history is not worth the attention of future
readers of "git log" who need to study the history, assuming that
trivial mistakes are caught early.  Once earlier rounds of review is
done and everybody is more or less happy, the topic gets merged to
'next', and after that point, a new issue that gets noticed and
fixed _are_ worth recording in history, because both the original
contributor and reviewers failed to catch such glitches.

> I'm curious to know if I went wrong somewhere and the workflow and would be
> glad to propose another patch to improve SubmittingPatches with a section of
> what to do when patches show up in `seen`, but since I'm a n00b (at least as
> an upstream Git contributor :), I'd need to know how to DTRT in this case to
> do that.

I thought your v3 did things perfectly.

Thanks.