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

From: Bradley M. Kuhn <bkuhn@sfconservancy.org>
Date: Oct 20, 2020, 21:28 UTC
Message-ID: <20201020212820.GA1368742@ebb.org>
In-Reply-To: <20201020023407.GB54484@nand.local>

Taylor Blau wrote:

> Thanks; I think some of our emails crossed over one another, but this
> version looks good to me.

Yes, I was preparing the patch when you wrote that you disagreed with Junio and preferred the ":".

FWIW, I left the ":" anywhere headers were being discussed and those headers were described with ":"s on them. I only changed places where "Signed-off-by:" stood alone.

Before my v3 patchset, usage was inconsistent about (roughly half/half), so the decision is mostly a coin toss. I didn't have a strong opinion when I was first writing the v3 patchset, but having thought about it overnight, I now think leaving the ":" *out* is better because a reader new to Git is more likely to think a ":" is punctuation, rather than being part of a moniker. Thus, IMO, leaving out the ":" in most cases probably improves readability.

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:

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'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. -- Bradley M. Kuhn - he/him Policy Fellow & Hacker-in-Residence at Software Freedom Conservancy ======================================================================== Become a Conservancy Supporter today: https://sfconservancy.org/supporter