From: "Junio C Hamano" <gitster@xxxxxxxxx>
: Friday, November 10, 2017 1:24 AM
[catch up]
"Philip Oakley" <philipoakley@xxxxxxx> writes:
From: "Stefan Beller" <sbeller@xxxxxxxxxx>
Rereading this discussion, there is currently no urgent thing to
address?
True.
Then the state as announced by the last cooking email, to just cook
it, seems
about right and we'll wait for further feedback.
A shiny new toy that is not a fix for a grave bug is rarely urgent,
so with that criterion, we'd end up with hundreds of topics not in
'next' but in 'pu' waiting for the original contributor to get out
of his or her procrastination, which certainly is not what I want to
see, as I'd have to throw them into the Stalled bin and then
eventually discard them, while having to worry about possible
mismerges with remaining good topics caused by these topics
appearing and disappearing from 'pu'.
I'd rather see any topic that consumed reviewers' time to be
polished enough to get into 'next' while we all recall the issues
raised during previous reviews. I consider the process to further
incrementally polish it after that happens a true "cooking".
For this topic, aside from "known issues" that we decided to punt
for now, my impression was that the code is in good enough shape,
and we need a bit of documentation polishes before I can mark it
as "Will merge to 'next'".
Possibly only checking the documenation aspects, so folks don't fall
into the same trap as me.. ;-)
Yup, so let's resolve that documentation thing while we remember
that the topic has that issue, and what part of the documentation
we find needs improvement.
I am not sure what "trap: you fell into, though. Are you saying
that giving
git describe [<option to describe a commit>...] <commit-ish>
git describe [<option to describe a blob>...] <blob>
in the synopsis is not helpful, because the user may not know what
kind of object s/he has, and cannot decide from which set of options
to pick? Then an alternative would be to list
(If I remember correctly) My nit pick was roughly along the lines you
suggest, and that the two option lists (for commit-ish and blob) were shown
in different ways, which could lead to the scenarion that, with knowing the
oid object type (or knowing how to get it), the user could give an invalid
option, and think the command failure was because the oid was invalid, not
that the option was not appropriate, along with variations on that theme.
The newer synopsis (v5) looks Ok in that it avoids digging the hole by not
mentioning the blob options. Personally I'm more for manuals that tend
toward instructional, rather than being expert references. I'd sneak in a
line saying "The object type can be determined using `git cat-file`.", but
maybe that's my work environment...
git describe [<option>...] <object>
in the synopsis, say upfront that most options are applicable only
when describing a commit-ish, and when describing a blob, we do
quite different thing and a separate set of options apply, perhaps?
--
Philip
