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

Marc Branchaud [off-list ref] writes:

quoted

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

quoted

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

quoted

+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?

quoted

+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 [off-list ref]"
+------------
+
+provided if the signature in the signed tag verifies correctly. Notice

s/if //

Noted.

quoted

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

s/list/list the/

Noted.

quoted

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

quoted

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