Pushing after merge considered harmful

[Eli Zaretskii]

> Date: Tue, 26 Jan 2010 09:08:51 -0600
> From: "Matthew D. Fuller" <fullermd at over-yonder.net>
> Cc: Eli Zaretskii <eliz at gnu.org>, Alexander Belchenko <bialix at ukr.net>,
> 	bazaar at lists.canonical.com
> 
> On Wed, Jan 27, 2010 at 12:04:21AM +0900 I heard the voice of
> Stephen J. Turnbull, and lo! it spake thus:
> > 
> > That reads like an indictment of the Bazaar UI to me.
> 
> It's an indictment of any non-trivial system.  There's always
> emergent behavior, and to try and pass understanding along from the
> top down is like trying to keep somebody alive by feeding them carbon
> atoms.

Oh, come on!  Try the Emacs Lisp Manual some day: it describes a
vastly more complex system than Bazaar, and yet if you read a chapter
on some issue, you get enough information to understand that issue
from close to zero knowledge to the degree that you can write a
non-trivial Lisp application.

Yes, it takes effort to produce such a high-quality documentation, and
of course the ELisp manual prints in two 700-page volumes, but hey!
who said that a complex system can be explained in two sentences?

It doesn't mean you cannot do that in principle, though.  It doesn't
mean you shouldn't try, either.  I doubt that you will need more than
a few dozen pages to describe Bazaar in sufficient detail.  You just
need to do it, methodically, thoroughly, from the ground up.

> Armed with the underlying understanding, it's very easy to ask
> yourself "does operation X involved changing the branch pointer", and
> so figure out whether the param can mean anything.

Right, except that the ``underlying understanding'' is nowhere to be
gleaned except in random Web pages and discussions such as this one,
by asking seemingly stupid questions.

How hard could it be to explain the effect of a few commands on a DAG?
Do that in some orderly fashion, and the rest is indeed trivial.  We
are programmers here, we know what a DAG is, or can learn in a few
minutes.

> Asking after it the other way around basically boils down to "explain
> what $X is doing without having to understand what $X does".

No one asked that.  Please don't mock.  It's insulting.  I was asking
the questions in every possible form because without clearly explained
effect of each of the popular bzr commands on the history, in what
other terms do you expect me to ask questions?

Just a random example: your terminology when you explain the option we
were talking about.

   Push/pull move the branch pointer ...

What is a branch pointer? where does it point? and what does it mean
to "move" it -- move where?  There's nothing in the Bazaar docs that I
could find about this subject.  How am I supposed to understand what
you tell me, if we don't even have a common language and a common
system of terminology?

Oh, I am not a toddler.  I can _guess_ what you mean by these, and I
will probably be not far off the target.  But why should I invoke
guesswork in such fundamental matters, which you yourself say are "the
Gestalt of Bazaar"?  Can someone imagine that an Emacs Lisp programmer
would need to guess what does "cons" mean in the phrase "cons cell"?

What does all this have to do with Bazaar being a non-trivial system?
Nothing.  It has everything to do with the fact that it is
fundamentally an _undocumented_ system, and that most of the knowledge
about it is based on hearsay -- unless you are a Bazaar developer, I
guess.

> Trying to pass information along as that bunch of special cases is
> doomed to failure

Don't special-case, then.  Explain it from the ground up.  Draw a
sample history DAG, then show how it changes with `commit', with
`push', and with `merge'.  Then show on the same DAG what changes
a_r_o precludes.  That's it, case closed.

> While there ARE unfortunately some ugly special cases in bzr (the
> bound/checkout thing being high on the list), MOST of the behavior
> is Obvious(tm) from the interaction of the rather few underlying
> pieces.

I believe you.  But to use a system effectively, users must understand
it to a degree that allows them to build a mental model of the tool
which is close enough to reality.  Sadly, Bazaar docs of _any_kind_ is
not even close to allow one building such a model.  So we are here
asking questions without even knowing the terminology -- because it,
too, is not documented.  What else can we do?

Sorry if I sound blunt.  It is one thing not to know what questions to
ask in order to DTRT with Bazaar.  It's another to be told that
there's no way _in_principle_ to answer some questions, because the
questor must possess some secret knowledge that is nowhere to be found
within reasonable time and amount of effort.