Arch for core LNX-BBC developers

This section assumes that you have a gargoyle account and are in the src group. That means that you were using CVS to do LNX-BBC development before.

Step One

Before you begin playing with arch, it is important to register your e-mail with the client configuration. For example:

$ tla my-id "Ugly Troll <haesslich@zork.net>"

To see if you already have this configured, just run "tla my-id" at the shell.

All examples from here on out will use the mythical user "haesslich".

In CVS, we had two branches: STABLE and HEAD. Of these, HEAD was sort of the "trunk", and STABLE was a more restricted branch off of it. Arch treats all branches as peers, and you will find yourself making new branches in much the same way that you make new directories to store data associated with discrete tasks.

The two official branches on gargoyle are called "stable" and "research", and correspond to STABLE and HEAD from CVS, respectively. The full descriptors right now are lnx-bbc--stable--2.1 and lnx-bbc--research--0.0. Stable was built by first importing RELEASE_lnx-bbc_2_1 to form lnx-bbc--stable--2.1--base-0, and then brought up to the latest STABLE CVS state to form lnx-bbc--stable--2.1--patch-1. Thus, it can be considered to be "version 2.1 patch-level 1" on the road to 2.2 or 3.0.

gnupg

The branches on gargoyle make use of arch's gnupg support. This means that no checkins to the two official branches will be accepted without a gpg signature! Thus, there are a few steps to take before you begin working with the official branches.

Also, you ought to have gnupg 1.2 or better in order to have the keyserver functions we make use of. If you're running debian stable, consider adding the following line to your /etc/apt/sources.list:

deb http://www.backports.org/debian stable tla gnupg

This is how gargoyle gets its copies of arch and gpg.

Make a key

We plan to generate a keyring just for the lnx-bbc project, and use that to verify changeset signatures. You ought to make a fresh new key for the lnx-bbc project. We recommend using your @lnx-bbc.com address (the username is your username on gargoyle), since it is somewhat of a role account.

$ gpg --gen-key

I made mine DSA-only, since it is only used for signatures and not encryption.

Configure arch to use your key

Now you need to tell your arch client how to use this key

Send your key to a public keyserver

For your signed changes to be verified by other developers your public key needs to be available on a keyserver. Here's how you put your key on the server:

$ gpg --keyserver subkeys.pgp.net --send-keys haesslich@lnx-bbc.com

Check out a branch

Now you're ready to start grabbing sources.

Register the archive

Arch uses a naming scheme that is, truth be told, somewhat overengineered. Archives (think repositories in CVS) are of the form e-mail@host--some-name, so we use the lnx-bbc-devel list as the e-mail, and "gar" for the name. Simply register this archive name with an sftp (ftp over SSH) URI, and you'll have remote access to the archive using the same credentials you used to use for CVS.

$ tla register-archive sftp://haesslich@arch.lnx-bbc.com/var/www/arch/

Now let's verify that we can see this archive

This may be slow for you, since gargoyle is on a badly lagged network. Fortunately, that is less of a handicap with arch than it was with CVS!

Get the stable branch

$ tla get lnx-bbc-devel@zork.net--gar/lnx-bbc--stable--2.1

You should have a directory now with a name like "lnx-bbc--stable--2.1--patch-1". Feel free to move it to a more manageable name, or you can specify the directory name as the second option to "tla get".

Keep your tree up to date

Arch updates working trees pretty much just like CVS does.

$ cd lnx-bbc--stable--2.1--patch-1
$ tla update

Make your own branch

It is possible at this point for you to edit a file and simply "tla commit", if you are in a big hurry. This has the advantage of being the most CVS-like, and probably the most familiar to you.

Doing things that way, however, deprives you of many of the features arch offers. The workflow for an arch project is much more distributed, and allows you to leave several sub-projects and lines of development simmering in parallel.

Make your own archive

First you should make an archive to store your personal branches in.

$ tla make-archive --listing haesslich@zork.net--projects ~/.archive/

Since this is your personal archive, you should make it the default.

$ tla my-default-archive haesslich@zork.net--projects

As with "my-id", you can run "tla my-default-archive" on its own to see what your default is.

Make a package to store the branch in

Each branch you make must have a package (think modules in cvs) to be stored in. You're basically just allocating a name for it the way we allocated lnx-bbc--stable--2.1 for one of ours.

$ tla archive-setup lnx-bbc--uglification-project--0.1
* creating category haesslich@zork.net--projects/lnx-bbc
* creating branch haesslich@zork.net--projects/lnx-bbc--uglification-project
* creating version haesslich@zork.net--projects/lnx-bbc--uglification-project--0.1

Notice that the three parts of a package's name are called the "category", "branch", and "version".

Tag a branch off of stable

$ tla tag lnx-bbc-devel@zork.net--gar/lnx-bbc--stable--2.1 lnx-bbc--uglification-project--0.1
gpg: Signature made Tue 13 Apr 2004 04:46:10 PM PDT using DSA key ID 190F5A01
gpg: Good signature from "Nick Moffitt (GARchitect) <nick@lnx-bbc.com>"
gpg: WARNING: This key is not certified with a trusted signature!
gpg:          There is no indication that the signature belongs to the owner.
Primary key fingerprint: EB97 A815 2FD2 3960 5F40  AEB3 AC9D F37D 190F 5A01
gpg: Signature made Tue 13 Apr 2004 04:52:31 PM PDT using DSA key ID 190F5A01
gpg: Good signature from "Nick Moffitt (GARchitect) <nick@lnx-bbc.com>"
gpg: WARNING: This key is not certified with a trusted signature!
gpg:          There is no indication that the signature belongs to the owner.
Primary key fingerprint: EB97 A815 2FD2 3960 5F40  AEB3 AC9D F37D 190F 5A01
* Archive caching revision
* from pristine cache: lnx-bbc-devel@zork.net--gar/lnx-bbc--stable--2.1--patch-1
* patching for revision: haesslich@zork.net--projects/lnx-bbc--uglification-project--0.1--base-0
* Made cached revision of haesslich@zork.net--projects/lnx-bbc--uglification-project--0.1--base-0

The gpg output at the beginning just tells you that the changesets that stable is made up of are all signed properly, but you don't recognize the signature. The rest of the output shows that the latest version of stable has been packed up and made into a tarball to serve as the base-0 beginning of your new branch.

Work on your new branch

Check out your new branch from your archive

Now make some changes, working toward some goal. As you complete the sub-components, start maintaining your changelog in another window.

$ vi `tla make-log`

When your feature or fix is complete, run some sanity checks

Silence from tree-lint is always a good sign, and what-changed tells us that we edited CREDITS, and that's about all. Now we can check our work into our branch in our local archive. Since haesslich didn't do the "vi `tla make-log`", he has to enter his log now.

$ tla commit

1 Summary: Added haesslich to CREDITS
2 Keywords: ugly credits CREDITS haesslich
3
4 Gave Ugly "haesslich" Troll the CREDIT he deserves!
~
~

M  CREDITS
* update pristine tree (haesslich@zork.net--projects/lnx-bbc--uglification-project--0.1--base-0 => lnx-bbc--uglification-project--0.1--patch-1)
* committed haesslich@zork.net--projects/lnx-bbc--uglification-project--0.1--patch-1

Since our local archive doesn't require signatures, there was no gpg magic.

Fold in work other people put into the official branch

While you work, development does not halt! Barring some sort of code freeze, other developers are checking code into the official branch while you're wrestling with your particular problem. Folding their work into your branch is a good way to resolve conflicts without stopping all your work in other branches, and you can even do it with a separate working copy if you like.

$ tla get lnx-bbc--uglification-project--0.1 merge-copy
$ cd merge-copy/
$ tla star-merge lnx-bbc-devel@zork.net--gar/lnx-bbc--stable--2.1

While CVS scatters diff3 options about your files, delimited by sequences of less-than and greater-than signs, arch prefers to simply store conflicts in .rej files. If you don't have any .rej files, then you don't have any conflicts! Otherwise, resolve the conflicts and "tla commit" your merged version into your local archive and branch. Note that the changelogs for the merged changesets will be in your log automatically!

Once you've committed, you can safely update your main development branch and finish what you were doing.

$ cd ..
$ rm -rf merge-copy/
$ cd lnx-bbc--uglification-project--0.1--base-0
$ tla update

Publish your work to the official branch

Remember how we had you check out the gargoyle stable branch in the beginning? Well you really didn't need to use it until now. All you're doing is the reverse of what you did to merge someone else's upstream changes into your local branch:

$ cd lnx-bbc--stable--2.1--patch-1/
$ tla update
$ tla star-merge haesslich@zork.net--projects/lnx-bbc--uglification-project--0.1
$ tla commit

Again, when you commit your star-merged changes, you should see all of the changelog entries you wrote while working locally appear in the log for the official branch.

Next»