From: Daniele Segato Date: Fri, 26 Jul 2013 17:19:54 GMT Subject: Re: [PATCH] git-tag man: when to use lightweight or annotated tags Message-ID: <51F2AFBA.4020602@gmail.com> In-Reply-To: <51F28D08.8050507@xiplink.com> On 07/26/2013 04:51 PM, Marc Branchaud wrote: > On 13-07-26 04:46 AM, Daniele Segato wrote: >> From 34fdcb56e5784699ffa327ebfcd2c5cd99b61d2d Mon Sep 17 00:00:00 2001 >> From: Daniele Segato >> 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]". Thanks, I'll try to do the right thing with the next patch. By the way which is your role in the community? Don't want to be rude, I just don't know who I'm talking about :) the documentation maintainer? Thanks for the help anyway. >> 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 ` 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". Ok > > 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. > Ok, English is not my native language so no surprise it sound awkward ;) I'll follow your suggestion here and move everything later. >> Unless >> `-m ` or `-F ` 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. > I tried to take into account everything you said to me and rewrite the patch, following this message. Regards, Daniele