ANNOUNCE: CVS to arch gateway

[Mike Hearn]

Hi everybody,

I'm pleased to announce the public availability of a gateway from WineHQ CVS
to the GNU arch version control system. 

It marks the beginning of an experiment not just in new forms of source 
control, but in new ways for the Wine project to be organized and
function. Nobody knows if it will catch on, but a few of us (me, dimi and
alexandre) have been discussing trying out arch for some time. Carpe dium!

====================================================================

For those who already know arch, here are the details:

archive coordinates:

http://navi.cx/mike/wine/archive
	mike at winehq.org--wine/wine--mainline--0.9

It is synchronised with CVS on the hour, every hour and a cacherev is
generated once a week. There are a couple of useful scripts in the root
directory, branch and merge which are described in the README.ARCH file.

It is mirrored here:

http://mirrors.sourcecontrol.net/mike@winehq.org--wine/

For your convenience, and for people who have never used arch before,
here is an adapted form of the README file. It's available in pseudo-HTML
here:

http://navi.cx/~mike/wine/

=====================================================================

README.ARCH
Mike Hearn <mike at navi.cx>

GNU arch is a distributed source control system. Unlike CVS, arch
trees can be branched and branched again with no write access to the
original archive. It has a variety of other interesting features -
for instance, it uses atomic commits and can operate using a variety
of network protocols. For more information see http://wiki.gnuarch.org

The rest of this readme is going to take the form of a tutorial on
how to use arch with Wine. We'll start with the really basic tasks
that even non-developers may wish to use, and work up to advanced
usage (branching and merging). It will not answer every question you
have, for that use the wine-devel mailing list for discussion :)


* Tracking Wine development
---------------------------

You might not be reading this file from an actual arch project tree,
so let's start with how to get a copy of the gateway tree. First of
all you need to install "tla", the reference implementation of
arch. You can get it from the gnuarch.org website, but a simpler way
is to use the prebuilt binary available here:

  http://www.navi.cx/~mike/wine/tla

Download, chmod +x, copy to /usr/local/bin and you're set. The binary
should work on any Linux distro. Yes, it's large, the arch build
system contains local copies of various libraries.

Now it's installed, run the following command:

     tla register-archive http://www.navi.cx/~mike/wine/archive/

Once it's registered succesfully (you get a message when that
happens), you can run the following command to check out the tree:

     tla get mike at winehq.org--wine/wine--mainline--0.9 winehq

This will place a copy of the gateway tree into the winehq/
directory. "winehq" is a good name to use, because you may later wish
to download other branches or even make your own, but there will only
ever be one WineHQ tree - the one controlled by Alexandre Julliard.

Yes, I know mike at winehq.org isn't a valid email address, it doesn't
matter, the email is only for namespacing and identification reasons :)

The checkout will take a long time even on a fast link: the Wine
sources are 10mb.

Once downloaded, updating the tree is easy:

     tla update

So, now you have an arch project tree, what can you do? Arch has a
lot of interesting commands, try "tla changelog | less" and "tla
missing -s".

Have fun!


* Simple development
====================
    
The easiest way to use arch for development is the same way we use
CVS: by making changes in a tree, generating a diff from those
changes, then emailing in the patch. Let's see how that works.

First of all, we make a change to the tree. Then we use:

     tla changes --diffs

to get a patch. In fact, this will generate a lot of extra stuff
that you don't really need - feel free to remove it, but it's not
required; patch can strip out garbage from patches automatically.

You can get diffs for individual files with "tla file-diffs".

Be warned! These commands work against the last revision you updated
to, they do *not* work against the latest version in the remote
archive like CVS does. So you probably want to update first.

However, unlike people just tracking the tree, you DO NOT want to use
update! What update does, roughly speaking, is reverse changes made
to the tree, apply the missing patches in turn, then reapply the
changes. If there are any conflicts they appear in patch style .rej
and .orig files.

There is a better way. Arch has a very interesting and powerful
command called "star-merge". Star-merge allows you to merge your tree
with another tree (subject to certain rules), in a Just Works(tm)
fashion. It will deal with repeated merges, and it works if the
person you are merging from previously merged with you.

To make this simpler, I've written a script that figures out what you
branched from (if anything), and then merges from it.
In effect, this is like "cvs update".

     ./merge

This operation can be quite slow (because it involves constructing
multiple trees and comparing etc), but it is generic and will work
both with the gateway tree and branches - and it gives 3-way merge
inline conflict markers too.

If you want to do it faster, and you don't mind having patch style
.rej files generated in the case of conflicts, try:

     tla replay

which simply downloads and applies each patch in turn. "tla update"
does work too, why not try them all to see which you prefer?


* More advanced development
===========================

So, here comes the interesting part. Now we've covered the basics,
it's time to find out how to make our own branches and commit to them.

You need to do a bit of setup. Firstly, you need to tell arch who you
are:

     tla my-id 'Mike Hearn <mike at navi.cx>'

You have to use an ID of this form, arch won't accept others. Now you
need to create your own archive.

An archive is a rough equivalent of a CVS repository with one key,
fundamental difference: an archive is a personal thing which can
contain trees from many different projects. Typically a person has
only one archive, though there's nothing to stop you having
more. Archives are just directories and files, no special server
software is required to run one. You just need some web space.

The basic workflow with arch goes something like this:

1) Write patch
2) Commit to branch
3) Upload to a mirror of your archive

Your actual archive is usually kept locally, which means you can work
and commit offline. You then mirror the archive on a remote machine
so others can access it. If people want to work on your tree, they
branch it, set up their own archive and then you pull from that. In
other words, only you have write access to your own archive.

So, you need to create a directory to hold your archive, like this:

    tla make-archive mike at navi.cx--2004 ~/Code/Arch/2004
    tla my-default-archive mike at navi.cx--2004

The named directory should not exist, but its parents should. An
archive name must have the form of an email address followed by two
dashes followed by a name. I've named it after the year of creation
which is pretty common, but it can be called anything.

Now, to speed things up, you probably want to create a revision
library. This is basically a cache (using hard links to be space
efficient) of revisions. You probably want it. Make one like this:

     mkdir ~/Code/Arch/RevLib
     tla my-revision-library ~/Code/Arch/RevLib
     tla library-config --sparse --greedy ~/Code/Arch/RevLib

OK. Now you just need some web space. Arch can write to web space
using ftp, sftp (ssh), or WebDAV. You probably want sftp. If you
don't have any web space you can use talk to me and I'll put you in
touch with people who can give you some space specifically for
hosting archive mirrors.

For now, don't bother with a remote mirror. Just play with a local
copy, that way you can delete things if you make a mistake (you can
delete a branch with rm -rf inside the archive, nothing will break).

Let's say you wish to branch the WineHQ tree, and start work on the
winecfg program. The simplest way to do this is to create a directory
somewhere that you will keep all your wine trees in. I use
/source/wine/arch. Then do this:

    tla get mike at winehq.org--wine/wine--mainline--0.9 winehq
    cd winehq
    ./branch winecfg

The branch script is in the root of the gateway tree, and is written
by me. It's designed to let you rapidly branch a given Wine tree. It
works by "tagging" the new tree in arch, then duplicating the current
tree using hard links before finally forcing the duplicate tree to
the new branch.

WARNING! WARNING! WARNING! WARNING! WARNING! WARNING! WARNING! WARNING!

If you use the branch script you MUST use an editor that breaks hard links.
emacs does by default, vim does if you :set bkc=no (though be warned, this will
interfere with some programs that invoke vim like crontab -e). zile does not.

If you want to use an editor that does not break hard links you must
remove the -l option from cp in the branch script so a real duplicate
is made. This uses more disk space and is slower to copy, but is safer.

The result is a new directory called winecfg/ created as a sibling of
the current directory. You can now commit to this tree however often
you like. Running merge will update the branch from the tree you
branched from (in this example, the gateway tree).

You can branch from that tree again, and so on. Other people can
branch from your tree in the same way! Feeling giddy with power yet?
No? Good. Remember that patches which aren't in the mainline tree
aren't reaching 99.9% of the users - being able to branch is useful
but don't use it as an excuse to not get patches upstreamed!

The new branch is put in the default archive and the name is derived
from the current, for instance running branch in
mike at winehq.org--wine/wine--mainline--0.9 with the parameter "winecfg"
produces a branch with the name mike at navi.cx--2004/wine--winecfg--0.9

Now you need to publish a mirror:

    tla make-archive --mirror mike at navi.cx--2004 sftp://navi.cx/home/mike/public_html/archive

and update it when you have done some commits

    tla archive-mirror

which actually uploads the changes. If you are always connected, you
can run the first make-archive command (back when you created your
archive) with a remote location straight away, but doing it locally
then mirroring is more common.

Finally, tell people the URL of your archive so they can register it
and grab your tree. That's it!

Have fun! If you have any questions ask them on the wine-devel
mailing list.