Deleted mail

94a0d4530911171348r638e6071w23870c870d8f3d48@mail.gmail.com

On Tue, Nov 17, 2009 at 2:06 PM, Nanako Shiraishi <nanako3@lavabit.com> wrote:
> Quoting Felipe Contreras <felipe.contreras@gmail.com>
>> Right, your explanation is more clear:
>
> You have a funny way of saying "I'm sorry, I wasn't constructive,
> and my attitude repelled many participants from the discussion".

That's because that's not what I said. If my succinct counter-argument
to a side-topic repelled some people from the much more serious
discussion, that's fine for me, because it means I'm not making myself
clear and I have to try something else.

>> the fact that we need both
>> doesn't mean we cannot use the term "stage". As to "constructive
>> proposal" I deliberately tried to avoid them in case somebody tried to
>> disregard it as bike-shedding, and move on.
>
> If the only constructive proposal you could make is to replace
> words used in two operations without clarifying concepts any
> better to newbies, then what you are doing is bike-shedding.
> I don't think trying to hide that by not making any proposal
> changes that.

So what you are saying is: if I see a problem, and I cannot come up
with a "constructive" proposal, I should keep my mouth closed?

I'm not going to pretend that I have the magic solution because I
don't, but I do see a problem, and I do think it's not easy to solve,
that's why I think the git community should come up with a solution,
not just me. This solution in order to be effective most probably will
be quite drastic. If I cannot convince the community right now that
there's a serious problem, then I don't think any drastic proposal is
going to fly.

I might I have to wait for the next user survey, and make sure it's
design includes direct questions to understand how much people are
using the git stage, if it turns out very few people do (which I think
is already obvious), only then make a serious proposal to re-architect
the stage. That's OK for me.

>> What I'm trying to do is
>> bring up the issue that the stage is not user friendly.
>
> I thought you were the one who wanted to use "stage" everywhere?

I did want that at some point (and so did many people), but then
people brought up the different ways to add things to the stage
(primarily because I never use them), and then I stepped back in order
to think more. But the proposal that was "mine" was to change the
semantics of 'git stage' so that "git diff --stated" becomes "git
stage diff", thinking a bit more, "git apply --cache" could become
"git stage --only apply".

> For what it's worth, "stage" isn't very user friendly to me;
> maybe it is because I'm not a native English speaker. I'm not
> saying that when I hear "index" or "cached" I'll understand
> what they mean even if I didn't have any prior knowledge of
> git, but I am saying "stage" isn't any better than these two
> words in that respect. Of course the user needs to understand
> what it is and how it is used, no matter what word you use.

I'm going to change my usual blunt style and try to be sensitive here:
I'm not trying to blame you, or disregard your background. I'm not a
native English speaker either (although my tongue language is a
romance one, so perhaps I have some advantage), but to me, English is
a language of short words, and therefore, the exact word you pick
makes a world of difference, and this is something I feel many
non-english speakers don't appreciate. Since we all are communicating
in English, I think we should not disregard "subtle" differences in
words such as "cached" and "stage" that might not mean much to you,
but I think it would to the thousands (or millions) of git users who
do understand immediately the meaning of "stage" regardless of their
git (or any other SCM) background.

So, I invite you to explore a bit the word "stage" (this all is coming
from wikidictionary[1]:

= Etymology =
From Middle English, from Old French estage (“story of a building,
performance stage”), from Vulgar Latin *staticum from Latin statum,
past participle of sto (“to stand”)

All checks here, git's stage can be compared to the "story of a
building", or a "performance stage", and certainly is something that
"stands".

= Noun =

1) a phase
He is in the recovery *stage* of his illness.

Check; git's stage is a phase.

2) The area, in any theatre, generally raised, upon which an audience
watches plays or other public ceremonies.
The band returned to the stage to play an encore.

Check; git's stage raises from other places.

3) Short for stagecoach, an enclosed horsedrawn carriage used to carry
passengers
The stage pulled into town carrying the payroll for the mill and three ladies.

Not really sure about this one; the stage does carry something, but it
doesn't seem to fit perfectly. In any case, no negative points.

4) (electronics) the number of an electronic circuit’s block, such as
a filter, an amplifier, etc.
a 3-stage cascade of a 2nd-order bandpass Butterworth filter

Not really I guess, but no negative points.

5) The place on a microscope where the slide is placed
He placed the slide on the stage.

I don't think this an appropriate definition, but still fits.

= Verb =
1) To produce on a stage, to perform a play.
The local theater group will stage "Pride and Prejudice".

Commits aren't really played, but we could say the workdir is "behind
the curtains" and the stage is where the things for the public go.

2) To demonstrate in a deceptive manner.
The salesman’s demonstration of the new cleanser was staged to make it
appear highly effective.

Yes and no; in some way we are hiding the horrible mess that happens
in the workdir :)

3) (Of a protest or strike etc.) To carry out.

Kinda.

4) To pause or wait at a designated location.
We staged the cars to be ready for the start, then waited for the
starter to drop the flag.

Perfect check.

> I think a proposal to replace the word "index" with "stage"
> will sound nothing but bike-shedding to anybody, especially
> after getting familiar with "index" and seeing it taught on
> many web pages and books.

I'm sorry but I have to use the --gogo argument here: even if you got
familiarized with --gogo, and it was taught on many web pages and
books, that doesn't make it an English word that correctly describes
what it's doing in git. "index" already has a meaning in the English
language:

From Latin index (“a discoverer, informer, spy; of things, an
indicator, the forefinger, a title, superscription”) < indicō (“point
out, show”); see indicate.

In other words: an index is something that helps you find things,
usually these things are assigned identifiers for easy referral later
on, like the index of a book.

Let's accept the truth: the word "index" is used for historical
reasons in git, and not because it's a good match in the English
language to what it really does. There might be better alternatives,
and the only reason we are not using them is inertia, which is a valid
reason, but only for so long. So maybe this should change for 1.8.0,
or later.

>> I like David Kågedal's suggestion more:
> Yes, I had David's proposal in mind when I wrote my response.
> Even though the fundamental idea is the same, I used --X-vs-Y
> option to avoid the problems David's proposal has in a slightly
> nicer way.
>
> David's proposal introduced two magic tokens STAGE and WORKTREE.
>
>  git diff STAGE WORKTREE   (like "git diff" today)
>  git diff HEAD WORKTREE    (like "git diff HEAD" today)
>  git diff WORKTREE HEAD    (like "git diff -R HEAD" today)
>  git diff HEAD STAGE       (like "git diff --cached" today)
>  git diff commit STAGE     (like "git diff --cached commit" today)
>
> This looks nice on surface, but I think the apparent niceness
> is shallow. If of course has a small problem of introducing an
> obvious backward incompatibility. You can't use a branch whose
> name is STAGE anymore, but a deeper problem is that these two
> magic tokens pretend to be refs. But they do so only to the diff
> command. I don't see how you can make them sanely be usable to
> other commands like "git log v1.0.0..WORKTREE".

We already have a miss-match between commands:
git log v1.0.0 HEAD
vs
git diff v1.0.0 HEAD

Of course they do different things, you should understand those
commands in order to know what's happening.

Cheers.

[1] http://en.wiktionary.org/wiki/stage

-- 
Felipe Contreras