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

> 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]".

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