Re: [PATCH] pulling signed tag: add howto document

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

Marc Branchaud <marcnarc@xiplink.com> writes:

>> +A contributor or a lieutenant
>> +-----------------------------
>> +
>> +After preparing her work to be pulled, the contributor uses `git tag -s`
>> +to create a signed tag [*1*]:
>
> Given that the rest of the text refers to the gist of this footnote, I think
> it'd be better to put the note's text here instead of as a footnote.

Hmm, I'll try to see how well it reads after moving the text here. Thanks.

>> +
>> +------------
>> + $ git checkout work
>> + $ ... "git pull" from sublieutenants, "git commit" your own work ...
>> + $ git tag -s -m "Completed frotz feature" frotz-for-xyzzy work
>> +------------
>> +
>> +and pushes the tag out to her publishing repository [*2*]. There is no
>
> This footnote speaks of the example using a +, but the example does no such
> thing.
>
>> +need to push the `work` branch or anything else:
>> +
>> +------------
>> + $ git push example.com:/git/froboz.git/ +frotz-for-xyzzy
>> +------------

Do you not see the plus in front of +'frotz-for-xyzzy' above, or am I
missing something?

>> +In the editor, the integrator will see something like this:
>> +
>> +------------
>> + Merge tag 'frotz-for-xyzzy' of example.com:/git/froboz.git/
>> +
>> + Completed frotz feature
>> + # gpg: Signature made Fri 02 Dec 2011 10:03:01 AM PST using RSA key ID 96AFE6CB
>> + # gpg: Good signature from "Con Tributor <nitfol@example.com>"
>> +------------
>> +
>> +provided if the signature in the signed tag verifies correctly. Notice
>
> s/if //

Noted.

>> +repository (i.e. `git tag -l` won't list frotz-for-xyzzy tag in the above
>
> s/list/list the/

Noted.

>> +There is no need to fetch and keep a signed tag like `frotz-for-xyzzy`
>> +that is used for frequent "pull" exchange in the long term just for such
>> +auditing purposes, as the signature is recorded as part of the merge
>> +commit.
>
> I had trouble parsing this sentence.  I think part of the problem is that
> it's comparing the actual implementation to an earlier proposed design that
> was rejected.  So it's trying to sell the reader on a feature of the
> implemented design, but the reader doesn't care.
>
> How about this instead:
>
> There is no need for the auditor to explicitly fetch the contributor's
> signature, or to even be aware of what tag(s) the contributor and integrator
> used to communicate the signature.  All the required information is recorded
> as part of the merge commit.

Ok, that is much easier to read.

>> +
>> +
>> +Footnotes
>> +---------
>> +
>> +*1* This example uses the `-m` option to create a signed tag with just a
>> +single liner message, but this is for illustration purposes only. It is
>
> s/single liner/single-line/

Noted.

Thanks.