[Bese-devel] darcs and the two branches

[Attila Lendvai]

hi!

to answer Evrim's question, here's a much simplified description of
how darcs works and it's consequences to dev/ajax (it contains useful
info for other developers, so i send this to the list).

when you darcs get a repo then you can think of two repos as two
versions of the same identity (for sure, darcs get doesn't make a new
project... but while a cvs checkout is a completly separated copy, a
darcs branch can be a bit smarter) so you can freely pull/push patches
between the two repos. in fact this is what happens when you record a
patch and push it to the dedicated public repo. you can think of your
local copy as a branch, and in fact any branching with darcs happens
just like that. the ajax branch is simply a darcs get of dev some time
ago with several recorded patches waiting to be pushed to dev.

when patches are recorded it's stored in a diff format. darcs can
always rebuild the current state of the repo from these patches, and
in fact the primary state is in the ordered list of patches, not in
the files in the working directory. (darcs check compares the contents
of the dir with the successive application of all the patches) a
recorded patch also has a list of depended-on pathces that must have
already been pulled into a repo for the patch in question to apply.

when patches are pulled and there are no conflicts, they are added to
the list of patches. if there are conflicts then darcs tries to
resolve them (this is an exponential algorithm with no escape
currently) and annotate the pulled patch with the required 'merger'
hunks. when fails it leaves conflict annotations in the files in
working directory, so that you can resolve it by hand and record the
resolution as a new patch.

it's a bit sloppy wording, but recodring in dev basically means you
are _inserting_ patches into the list of patches (of the ajax branch),
while recording in ajax means you are _appending_ to this list, which
is less intrusive from the pov of darcs.

as long as there are no conflicts it works great, and is very
flexible. when conflicts come, things can be handled relatively easily
with some attention, except when darcs seemingly ends up in an endless
loop resolving conflicts. to avoid such situations either the branch
should be short-lived enough so the resolution of conflicts won't take
ages, or the two branches should only be modified so that there are no
conflicts, or at least no more then necessary.

in the lights of these, here's a fuzzy list of files that have many
new patches in the ajax branch. if you are planning to make changes to
these files in the dev branch, please either contact me before pushing
it to the official repo (to run a quick test to ensure that darcs can
still handle the situation) or try to pull the patch yourself into
ajax to see if it works. patching stuff in ajax is ok and is
encouraged when possible, because this branch is the one that is more
ahead in patches (about 130+ now) and has all the patches that dev
has.

files with big patch traffic in the ajax branch:
- per-application-parenscript.lisp
- ucw-tags.lisp
- l10n stuff
- window.lisp
- some action related files in rerl, but they have not that many changes...

i'm pulling the yaclml cleanup in ucw-tags.lisp for several days now,
and i'm not sure it'll finish sooner then a new version of darcs
coming out with an option to bail out and leave the conflict
resolution to me... :) and above all these i'm sure it will not apply
and will need a resolution by hand (which is 3 lines of code).

darcs is cool, but its design has its drawbacks that need to be taken
into account when branching.

hth,

-- 
- attila

"- The truth is that I've been too considerate, and so became
unintentionally cruel...
 - I understand.
 - No, you don't understand! We don't speak the same language!"

Ingmar Bergman - Smultronstället (Wild Strawberries)