Re: What's cooking in git.git (May 2013, #08; Tue, 28)

From: Ramkumar Ramachandra <artagnon@gmail.com>
Date: May 29, 2013, 18:15 UTC
Message-ID: <CALkWK0kwdm+CP=_EsWgEsBPACnMWpy9-hV5wjdWDXYggCntFpA@mail.gmail.com>
In-Reply-To: <7vvc61u1cc.fsf@alter.siamese.dyndns.org>

Junio C Hamano wrote:

Show 5 quoted lines

>> Is there something you're not happy with?
>
> By the way, you probably should stop thinking in terms of "me" being
> (un)happy.  I am just trying to help by preventing (collectively) us
> making silly mistakes.

As a general principle, okay.

IIRC, nobody else had comments on this one.

>> * publish-rev: the @{push} thing is still in the early poc stages.
>
> I presume this is the one that may someday lay foundations for Tytso's
> "do not rebase beyond this point, as I have published it already"?

Yep. More importantly, I'll get something I've been wanting badly: the tracking info in the prompt.

Show 5 quoted lines

>> * for-each-ref-pretty: not ready; working with Duy.
>
> I haven't been paying too much attention to it, but my impression
> was a "superset" syntax is coming?  That would be going in the right
> direction.

Yes, a superset with coming with one caveat: %ae will be interpreted as hex. I hope to send a large'ish series that also strips out the -v, -vv code. Duy basically did most of the work by coming up with a brilliant way to inject into the pretty-formats machinery.

Show 7 quoted lines

>> * pickaxe-doc: you had some more comments in latest iteration, but the
>> returns from a re-roll are diminishing.  Frankly, the work is too
>> boring: the first few iterations were interesting, because I was
>> learning;...
>
> Yeah, some parts of the project is boring and that is not a news.
> Think of documentation updates as helping others to learn.

See, the problem is that I might drop the ball on patches like this (I've done it before, when I thought the change wasn't important enough for me to bore myself). This is definitely important, and I will see it to completion. But I'm echoing a more general problem:

If people don't feel like working on it, how will the documentation improve? And if the pickaxe-doc was in such bad shape, how could anyone have been using it? Do an internet search and see for yourself. This feature is _extremely_ useful, and it's a real shame that it has been so poorly documented for this long.

I'm not advocating a lax review that checks in technically incorrect documentation; that will confuse users and turn it into a huge maintenance burden. But we can maybe go down a notch on style?