Re: Apologia for bzr

[Eli Zaretskii <eliz@gnu.org>]

> From: "Stephen J. Turnbull" <stephen@xemacs.org>
> Cc: Toby Cubitt <toby-dated-1389906911.cc0ede@dr-qubit.org>,
>     esr@thyrsus.com,
>     kfogel@red-bean.com,
>     emacs-devel@gnu.org
> Date: Sat, 04 Jan 2014 05:34:06 +0900
> 
> Eli Zaretskii writes:
> 
>  > At least in Emacs we have an excuse that the bulk of the
>  > terminology developed when no other software provided any similar
>  > features; there's no such excuse for git (or bzr or hg).
> 
> You're wrong about git, you're arguably right about bzr and hg.

What, git was the first VCS, and needed to invent a new terminology?

> Git is fundamentally different from bzr and hg, almost as different as
> it is from CVS and RCS.  Git is designed for use cases like "git
> filter-branch", it's easy enough to implement it as a shell script
> (though it would be slow), and probably it was prototyped that way
> (although I would write the prototype in Lisp, not shell).  I really
> wouldn't want to try to do that in hg or bzr: although it could be
> done, it would be unusably slow (because they don't have a separate
> index, so the work has to be done in-tree-on-disk, rather than only on
> metadata in memory).

What does this have to do with clear and comprehensible documentation?

>  > Anyway, there's a big difference here: in Emacs documentation,
>  > every term is explained before it is used, and rarely used terms
>  > have cross-references to where they are described.
> 
> I bet you can dip into any number of Info nodes where the terms
> "buffer" and "window" are used without definition.

I said "rarely used terms".  Frequently used terms need to be
understood in advance, by reading the preceding chapters.

In any case, buffer and window can be intuitively understood, much
more than "index" and "staging".

> The git "index" is equally fundamental to git.

But there is a way to explain what a commit does without ever
mentioning the index, certainly not in the sentence that _defines_
what a commit is.

>  > > >   Stores the current contents of the index in a new commit along with
>  > > >    a log message from the user describing the changes.
>  > > > 
>  > > > Huh?  "Contents of the index"?  I used to know what commit was, now I
>  > > > don't.
> 
> Sure you do; commit hasn't changed.  What you now know is what the
> index is: a data structure that contains the same information as a
> commit, but isn't a commit and isn't a working tree, either.

No, I don't know any of this, because it wasn't explained, not even in
a few words that would help me make it past the obstacle.

>  > You are missing the point: I didn't want a tutorial.  I use VCSes for
>  > many years, and dVCSes for some; I already know what it means to
>  > commit a changeset and what is the basic workflow of using a dVCS.
> 
> But I think you've misstated the case here.  Development has
> workflows, and dVCS usage is adapted to them.  It doesn't make sense
> to talk about "*the* basic workflow of using a dVCS".  You're actually
> talking about *your* basic workflow, and how you use a dVCS in that
> workflow.

No, I'm talking about *the* basic workflow: make changes, then commit
them.  Tutorials seldom go beyond that.

>  > "Recording a commit"? what's that?  And is "commit that has the exact
>  > same tree as its sole parent commit" a complicated way of saying "no
>  > changes since the last commit", or is there some important subtlety
>  > here that I'm missing?
> 
> It's probably not important to you, so I won't go into detail, but
> there are several subtleties that are missing from the simple
> expression "no changes since the last commit".

As there were a few subtleties missing from my mock description of
C-f.

>  >   --unchanged   Commit even if nothing has changed.
> 
> This makes a lot of sense in Bazaar, because Bazaar makes it hard to
> work nonlinearly without using multiple workspaces.

I was talking about clear documentation, not about the differences
between git and bzr.

>  > I want some decent reference documentation.
> 
> AFAICT, you want your dVCS to be Bazaar.

It doesn't matter what I want in this case, we all know what I will
get, right?  Since that's what I will get, I want its documentation to
be helpful.  Please don't misrepresent what I wrote by turning it into
another "git is more powerful than bzr" thread.  That is not what I
was talking about.

Anyway, I'm beginning to regret that I answered esr's question.  I
should have known what kind of "tide" will be unleashed on me.