git.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
From: Junio C Hamano <gitster@pobox.com>
To: Marc Branchaud <marcnarc@xiplink.com>
Cc: Junio C Hamano <gitster@pobox.com>, git@vger.kernel.org
Subject: Re: [PATCH] pulling signed tag: add howto document
Date: Wed, 18 Jan 2012 14:27:17 -0800	[thread overview]
Message-ID: <7v1uqwmyt6.fsf@alter.siamese.dyndns.org> (raw)
In-Reply-To: <4F173C5D.7000802@xiplink.com> (Marc Branchaud's message of "Wed, 18 Jan 2012 16:40:45 -0500")

Marc Branchaud <marcnarc@xiplink.com> writes:

> It might be better to just move the footnote to the end of the next sentence.

Ok. How does this version look?  The highlights are:

 * remove footnotes and spell them out inline, like "Note that..."

 * "a single liner" -> "a one-liner"

 * "publishing repository" -> "public repository". I often use the former
   when I want to differenciate a repository used to publish the work by a
   single owner from a shared public repository, so technically the wording
   could stay as-is, but I think it is clear that we mean publishing one
   not a shared one from the context of this document.

 * Drop the attempt to say "you would see these 'Good signature from...'
   if and only if the signature verifies OK" altogether. It is clear from
   the example that the signature was good.

 * Replace the paragraph that explains there is no need to keep and
   transfer signed tags for auditors with your version.

Thanks.

 .../howto/using-signed-tag-in-pull-request.txt     |   60 +++++++++----------
 1 files changed, 28 insertions(+), 32 deletions(-)

diff --git a/Documentation/howto/using-signed-tag-in-pull-request.txt b/Documentation/howto/using-signed-tag-in-pull-request.txt
index efac088..a1351c5 100644
--- a/Documentation/howto/using-signed-tag-in-pull-request.txt
+++ b/Documentation/howto/using-signed-tag-in-pull-request.txt
@@ -58,7 +58,7 @@ A contributor or a lieutenant
 -----------------------------
 
 After preparing her work to be pulled, the contributor uses `git tag -s`
-to create a signed tag [*1*]:
+to create a signed tag:
 
 ------------
  $ git checkout work
@@ -66,14 +66,27 @@ to create a signed tag [*1*]:
  $ git tag -s -m "Completed frotz feature" frotz-for-xyzzy work
 ------------
 
-and pushes the tag out to her publishing repository [*2*]. There is no
-need to push the `work` branch or anything else:
+Note that this example uses the `-m` option to create a signed tag with
+just a one-liner message, but this is for illustration purposes only. It
+is advisable to compose a well-written explanation of what the topic does
+to justify why it is worthwhile for the integrator to pull it, as this
+message will eventually become part of the final history after the
+integrator responds to the pull request (as we will see later).
+
+Then she pushes the tag out to her public repository:
 
 ------------
  $ git push example.com:/git/froboz.git/ +frotz-for-xyzzy
 ------------
 
-Then the contributor prepares a message to request a "pull":
+There is no need to push the `work` branch or anything else.
+
+Note that the above command line used a plus sign at the beginning of
+`+frotz-for-xyzzy` to allow forcing the update of a tag, as the same
+contributor may want to reuse a signed tag with the same name after the
+previous pull request has already been responded to.
+
+The contributor then prepares a message to request a "pull":
 
 ------------
  $ git request-pull v3.2 example.com:/git/froboz.git/ frotz-for-xyzzy >msg.txt
@@ -148,22 +161,21 @@ In the editor, the integrator will see something like this:
  # gpg: Good signature from "Con Tributor <nitfol@example.com>"
 ------------
 
-provided if the signature in the signed tag verifies correctly. Notice
-that the message recorded in the signed tag "Completed frotz feature"
-appears here, and again that is why it is important for the contributor
-to explain her work well when creating the signed tag.
+Notice that the message recorded in the signed tag "Completed frotz
+feature" appears here, and again that is why it is important for the
+contributor to explain her work well when creating the signed tag.
 
 As usual, the lines commented with `#` are stripped out. The resulting
 commit records the signed tag used for this validation in a hidden field
 so that it can later be used by others to audit the history. There is no
 need for the integrator to keep a separate copy of the tag in his
-repository (i.e. `git tag -l` won't list frotz-for-xyzzy tag in the above
-example), and there is no need to publish the tag to his public
+repository (i.e. `git tag -l` won't list the `frotz-for-xyzzy` tag in the
+above example), and there is no need to publish the tag to his public
 repository, either.
 
 After the integrator responds to the pull request and her work becomes
-part of the permanent history, the contributor can remove the tag from the
-publishing repository, if she chooses, in order to keep the tag namespace
+part of the permanent history, the contributor can remove the tag from
+her public repository, if she chooses, in order to keep the tag namespace
 of her public repository clean, with:
 
 ------------
@@ -199,23 +211,7 @@ A typical output from `git show --show-signature` may look like this:
        ...
 ------------
 
-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.
-
-
-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
-advisable to compose a well-written explanation of what the topic does to
-justify why it is worthwhile for the integrator to pull it, as this
-message will eventually become part of the final history after the
-integrator responds to the pull request.
-
-*2* The example uses plus at the beginning of `+frotz-for-xyzzy` to allow
-forcing the update of a tag, as the same contributor may want to reuse a
-signed tag with the same name after the previous pull request has already
-been responded to.
+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.

  reply	other threads:[~2012-01-18 22:27 UTC|newest]

Thread overview: 10+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2012-01-17 22:53 Using signed tag in pull requests Junio C Hamano
2012-01-17 23:29 ` [PATCH] pulling signed tag: add howto document Junio C Hamano
2012-01-18 15:15   ` Marc Branchaud
2012-01-18 21:22     ` Junio C Hamano
2012-01-18 21:40       ` Marc Branchaud
2012-01-18 22:27         ` Junio C Hamano [this message]
2012-01-18 22:35           ` Marc Branchaud
2012-01-18  1:07 ` Using signed tag in pull requests Andrew Ardill
2012-01-18  1:47   ` Junio C Hamano
2012-01-18  2:34     ` Andrew Ardill

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=7v1uqwmyt6.fsf@alter.siamese.dyndns.org \
    --to=gitster@pobox.com \
    --cc=git@vger.kernel.org \
    --cc=marcnarc@xiplink.com \
    --subject='Re: [PATCH] pulling signed tag: add howto document' \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).