[darcs-users] darcs patch: Edit Front Page (and 9 more)

[Stephen J. Turnbull]

Daniel Carrera writes:

 > It's easy to diss someone else's work.

I'm not "diss-ing" your work.  I'm criticizing it on the basis of the
standard "will this attract people who should be using Darcs to
Darcs?"

 > I offer the best thing I could come up with and I stand ready to
 > change when something better comes along.

To be blunt, I suggest <nothing> is better than "smart patch" or
"patch commutation", because they are claims that we can't
substantiate to the potential user (and may not even have really been
proved at all, depending on what connotations of practical advantage
you try to attach to them).

The website *should* contain discussion of these matters, for *our*
reference and discussion.  But the parts of the website aimed at new
and potential users should not, IMO.

How this stuff is presented in the "for the advanced user and Darcs
developers" section(s) is another question, much more unclear in my
own mind.  I basically think it should start from the "why *you*
will benefit from using Darcs" POV of the intro pages, deepen the
discussion into the "nuts and bolts" of patch theory (including the
patch commutation operator used for all patch reordering in Darcs),
and from there on to the speculative "why *we* think Darcs is really
cool" including both *best practices* like Spontaneous Branches and
*abstract theory* like Camp.

 > What do you think of "patch commutation"?

I think any mention of Mathematical[1] terms should be avoided:

    Someone told me that each equation I included in the book would
    halve the sales.  I therefore resolved not to have any equations
    at all.  In the end, however, I *did* put in one equation,
    Einstein's famous equation, *E = mc^2*.[2]

Seems quite apropros to me, both the general principle of avoiding
reference to Mathematics, and just how important and familiar the
exception needs to be to be allowed.

 > - "Darcs is special because it has patch commutation"

Any VCS that has a rebase operation has patch commutation, which is
all of them since CVS at least ("cvs update -j -j").  Darcs does it
automatically, but I think rather than call it "commutation" which is
the technical name for the primitive operation, we should call it
"ordering".  More stiff verbosity:

    Snapshot-based VCSes like Mercurial impose a partial historical
    order on changes, and in order to refer to a particular change or
    set of changes, you must refer to the particular pair of revisions
    whose diff is exactly that set of changes.  In the case of a set
    of changes, that pair may not exist, requiring many VCS operations
    on revision pairs to build up a "simple" set of changes.

    In Darcs, on the other hand, you *name* each *patch*, and you can
    request a set of patches by matching names.  Naming conventions
    can be as formal as "every patch name must begin with an issue
    tracker ID", allowing a query like "get me all patches related to
    'issue501'", or quite ad hoc, allowing a query like "get me all
    patches that fix a 'typo'".  And in the latter case, Darcs knows
    which typo fixes have already been applied, and automatically
    skips them when applying the patch set to your repo.  Note that
    although establishing a formal convention is very powerful, such
    ad hoc queries can be very convenient and useful too.

    Human programmers generally don't think about two patch sets that
    implement different features as being ordered.  Well, neither does
    Darcs.  Darcs will pull a set of patches that may implement
    several features, and automatically reorder them so that as many
    as possible apply without conflict.  You don't have to worry about
    it until a conflict arises, and Darcs can do this at least as well
    as you can, and faster.  Experience shows that when a conflict
    does arise, it is normally due to features that have genuinely
    conflicting requirements in the implementation, that some human
    must resolve.  This is exactly what you want.

 > - "Thanks to patch commutation, darcs can resolve conflicts more 
 >   predictably and reliably than any other VCS".

We don't really know that yet.  We know that Darcs will do something
useful with a conflict, and that it doesn't get in the way of merging
branches.  But that's true of git, too, in the sense that after
pulling a branch that conflicts with HEAD, that branch is now part of
your local repo and can be operated on just like any other git branch.
What fails is the integration of the two branches into a single new
revision.  In Darcs the semantics are somewhat different, but the
result is the broadly the same: your workspace contains a version of
the project which is not what you want, and requires further work by
you to get to what you want.

 > The front page could read:
 > 
 > Darcs is a free, open source, source code management system with many 
 > fabulous features:
 > 
 > * Distributed - ...
 > 
 > * Smart - Thanks to its Patch Commutation feature, darcs lets you 
 > cherrypick, merge, apply patches in different orders, ...

I don't see a real advantage here over

    * Smart - Darcs lets you cherrypick or merge from other branches,
      or apply patches in different orders, without unnecessary
      "bureaucracy".  You don't have to respect any historical order.
      Ie, you can specify *sets* rather than *sequences* of patches.
      And rather than some random hash or version number or position
      in a more or less meaningless sequence[3], you give patches
      names that make sense to you, and you can request their
      application by name in a very flexible way.

 > * Reliable - Patch Commutation is more reliable than the traditional 
 > 3-way merge because it is built on a sound foundation of mathematical 
 > theory. But you don't need to know the theory to use Darcs.
 > 
 > * Easy - ...
 > 
 > 
 > 
 > How does that sound? Even if you don't like it either, would you call it 
 > a step forward or a step back?

I'd call "patch commutation" a step sideways because (like "patch
theory" and "smart patch") it still makes a claim that the potential
user doesn't really understand and can't verify (Ganesh says it's not
even proved to be true yet).  At the same time it fails to demonstrate
any big advantages to the user (like, she'll go "if this is the best
you can offer, git has speed and a larger community of helpful people").

So, the general principles I'm advocating here are that (1) people
are going to find the identification of "implementation of behavior
features" with "patch set" *intuitive*, and (2) they will find Darcs
*attractive* because (a) the user interface, eg, interactive record,
makes construction of "coherent" patch sets *straightforward* and (b)
Darcs's implementation of branches makes selection of "features" (as
collected in patch sets) *straightforward* (ie, no extra bureaucracratic
requirement to respect the history of other branches).

Note that git has always had powerful revision and patch selection
features (eg, 'bisect' and the so-called 'pickaxe') and is acquiring
more (eg, the ":/" revision selector which matches the leading
characters of a patch log).  I think Darcs's UI does this better (and
that's by design).  The point is that I think git shows this is an
important feature of a VCS for lots of people, so we should emphasize
the convenience and power of the Darcs interface.

This UI-based appeal seems a little dull if you've drunk the "patch
theory" Kool-Aid, but the point of the home page and most related top
pages is to appeal to those who haven't gotten on to patch theory yet.

 > >  > Could you suggest an example of (b) [the distinction between
 > >  > "mv" and "darcs mv"]? I'm sure it would be useful in the
 > >  > documentation.
 > > 
 > > See my other post.
 > 
 > What other post?

<87ab6mqlk1.fsf at xemacs.org>, a reply to Eric in the subthread on the "swap
file names" example from Jason's thesis.

 > >  > I already lost confidence. How do I know if my project fits your
 > >  > definition of sane?
 > > 
 > > You're playing word games, because you have no text in front of you.
 > > Of course, I wouldn't use a word like "sane" at all[...].
 > 
 > Yes I did, I had your email. You used the word 'sane'.

There's a big difference between proposals for actual text to be
placed on the home page, and "meta" discussion of "the kind of thing
we should put on the home page".  Please try to keep that distinction
in mind or we're going to make very little progress.