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 <daniele.segato@xxxxxxxxx>
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 <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".
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 <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.
I tried to take into account everything you said to me and rewrite the
patch, following this message.
Regards,
Daniele
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html