Re: [PATCH] git-tag man: when to use lightweight or annotated tags

[Marc Branchaud <marcnarc@xiplink.com>]

On 13-07-26 04:46 AM, Daniele Segato wrote:
> From 34fdcb56e5784699ffa327ebfcd2c5cd99b61d2d Mon Sep 17 00:00:00 2001
> From: Daniele Segato <daniele.segato@gmail.com>
> Date: Thu, 25 Jul 2013 15:33:18 +0200
> Subject: [PATCH] git-tag man: when to use lightweight or annotated tags

When sending a patch to the list it's not necessary to include these headers,
as the git tools will extract them from the email itself.

Also, when sending a revision to a previously posted patch it's customary to
include a revision number, e.g. "[PATCHv2]".

> stress the difference between the two with suggestion on when the user
> should use one in place of the other.
> 
> Signed-off-by: Daniele Segato <daniele.segato@gmail.com>
> ---
>  Documentation/git-tag.txt |    7 ++++++-
>  1 file changed, 6 insertions(+), 1 deletion(-)
> 
> diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt
> index 22894cb..5c6284e 100644
> --- a/Documentation/git-tag.txt
> +++ b/Documentation/git-tag.txt
> @@ -26,7 +26,7 @@ to delete, list or verify tags.
>  Unless `-f` is given, the named tag must not yet exist.
> 
>  If one of `-a`, `-s`, or `-u <key-id>` is passed, the command
> -creates a 'tag' object, and requires a tag message.  Unless
> +creates a 'tag' object called 'Annotated tag', and requires a tag message.

1) Don't capitalize "annotated" -- it's not capitalized anywhere else in the
text.  The same goes for "lightweight".

2) I find the phrasing here awkward.  The important thing to convey is that
"annotated tag" is a synonym for "tag object".  The proposed text implies
that there can be other kinds of tag objects that are not annotated tags, but
I don't think that's true.  I've mulled over different ways of introducing
the "annotated tag" term here, but I can't come up with a succinct way to do
it.  I think it's better to just introduce the term later.

> Unless
>  `-m <msg>` or `-F <file>` is given, an editor is started for the user to type
>  in the tag message.
> 
> @@ -36,6 +36,11 @@ are absent, `-a` is implied.
>  Otherwise just a tag reference for the SHA-1 object name of the commit
> object is
>  created (i.e. a lightweight tag).
> 
> +'Annotated' and 'Lightweight' tags are not the same thing for git and you
> shouldn't
> +mix them up. Annotated tags are meant for release while lightweight tags are
> +meant for private or temporary object labels. Most git commands only consider
> +Annotated tags by default.
> +

I'm sorry, but I feel this misses the mark.

It's redundant to say the tag types are not the same thing, since the fact
that they have different names already implies that.  Also, to me the
admonition "you shouldn't mix them up" is just a scary warning that conveys
no helpful information.

Furthermore, I think simply stating that the tag types are meant for
particular uses without explaining why is too glib.  Although it may be
natural in your circumstances to think of the tag types rigidly, I do not
think that's true for all git users and I don't think the documentation
should assume there's a One True Way to use tags.

The text should give readers enough information to decide for themselves how
they want to use the different types of tags.  That's why I included the
annotated tag's contents in my suggestion, so that readers could figure out
which tag type best meets their needs.

What you've proposed is a step in the right direction, but I think you need
to go further.

		M.