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

[Taylor Blau <me@ttaylorr.com>]

Hi Bradley,

On Tue, Oct 20, 2020 at 02:28:20PM -0700, Bradley M. Kuhn wrote:
> The remainder of this email is purely an edification question that may help
> serve to improve Documentation/SubmittingPatches:
>
> > I'd be happy to discard what's currently in seen (integrated as 1b98087e0f
> > (Merge branch 'bk/sob-dco' into jch, 2020-10-19 at the time of writing) in
> > favor of what's here.
>
> 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:

The conclusive answer is that you can do anything you want when the
patches are in 'seen', but when it is in 'next', things have solidified
and the series is not meant to be changed. The one exception to that
rule is immediately after a release, in which case 'next' is rewound
(and thus some topics can be ejected from next).

> 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.
>
> and
>
> >> `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).
>
> The former hints that you *shouldn't* change the workflow if some of your
> patchset is in `seen`, and the latter hints that maybe you should, but
> neither section tells you what to do differently, if anything, once your
> patches are in `seen`.

I think the latter is really only talking about branches based on
'master' (of course, the same thing is true of branches based on any
branch, but it's uncommon to base topics off of 'seen').

The former is saying that 'seen' may change zero, one, or multiple times
during the lifetime of a topic. The latter says if you track upstream's
'master' and then 'git pull --rebase', 'git rebase' will tell you if
your patches are already applied upstream (in which case you can drop
them).

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

It couldn't hurt to add something to the effect of:

  Since 'seen' is a convenience branch that contains the current state
  of the in-flight topics, it is subject to be changed and rebuilt
  multiple times (c.f., link:howto/maintain-git) so the presence of your
  patches in 'seen' (but not 'next' or 'master') should not affect your
  workflow.

Thanks,
Taylor