How to use arch with the LNX-BBC project Since arch is relatively new, its documentation tends toward the general and the architectural. Tutorials are getting better, and lately the gnu-arch wiki has become an invaluable resource. The following documents are very useful: * * * * * So and start reading this tutorial. We hope to keep it strictly relevant to the lnx-bbc project. To start with, here's the nickel tour for using arch the same way you used to use CVS: === Setup === ----8<---- $ tla my-id "My Name " $ gpg --gen-key $ mkdir ~/.arch-params/signing/ $ echo 'gpg --default-key "" --clearsign' > ~/.arch-params/signing/\=default $ echo '/usr/bin/tla-gpg-check gpg_command="gpg --keyserver subkeys.pgp.net --keyserver-options auto-key-retrieve --verify-files -"' > ~/.arch-params/signing/\=default.check ----8<---- === Checkout === ----8<---- $ tla register-archive sftp://haesslich@arch.lnx-bbc.com/var/www/arch/ $ tla get lnx-bbc-devel@zork.net--gar/lnx-bbc--stable $ tla get lnx-bbc-devel@zork.net--gar/lnx-bbc--research ----8<---- === Update === ----8<---- $ tla update ----8<---- === Checkin === ----8<---- $ tla commit ----8<---- That should get you on your feet. To reap the benefits of the distributed workflow that arch allows, read on for the $7 tour. = 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: ----8<----- $ tla my-id "Ugly Troll " ----8<----- 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". == New names for the branches == 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: ----8<---- deb http://www.backports.org/debian stable tla gnupg ----8<---- 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. ----8<---- $ gpg --gen-key ----8<---- 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: ----8<---- $ mkdir ~/.arch-params/signing/ $ echo 'gpg --default-key "" --clearsign' > ~/.arch-params/signing/\=default $ echo '/usr/bin/tla-gpg-check gpg_command="gpg --keyserver subkeys.pgp.net --keyserver-options auto-key-retrieve --verify-files -"' > ~/.arch-params/signing/\=default.check ----8<---- === 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: ----8<---- $ gpg --keyserver subkeys.pgp.net --send-keys haesslich@lnx-bbc.com ----8<---- == 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. ----8<---- $ tla register-archive sftp://haesslich@arch.lnx-bbc.com/var/www/arch/ ----8<---- Now let's verify that we can see this archive: ----8<---- $ tla abrowse lnx-bbc-devel@zork.net--gar lnx-bbc-devel@zork.net--gar lnx-bbc lnx-bbc--research lnx-bbc--research--0.0 base-0 .. patch-1 lnx-bbc--stable lnx-bbc--stable--2.1 base-0 .. patch-1 ----8<---- 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 === ----8<---- $ tla get lnx-bbc-devel@zork.net--gar/lnx-bbc--stable--2.1 ----8<---- 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. ----8<---- $ cd lnx-bbc--stable--2.1--patch-1 $ tla update ----8<---- == 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. ----8<---- $ tla make-archive --listing haesslich@zork.net--projects ~/.archive/ ----8<---- Since this is your personal archive, you should make it the default. ----8<---- $ tla my-default-archive haesslich@zork.net--projects ----8<---- 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. ----8<---- $ 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 ----8<---- Notice that the three parts of a package's name are called the "category", "branch", and "version". === Tag a branch off of stable === ----8<---- $ 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) " 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) " 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 ----8<---- 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: ----8<---- $ tla get lnx-bbc--uglification-project * from archive cached: haesslich@zork.net--projects/lnx-bbc--uglification-project--0.1--base-0 * making pristine copy * tree version set haesslich@zork.net--projects/lnx-bbc--uglification-project--0.1 $ cd lnx-bbc--uglification-project--0.1--base-0/ ----8<---- Now make some changes, working toward some goal. As you complete the sub-components, start maintaining your changelog in another window. ----8<---- $ vi `tla make-log` ----8<---- When your feature or fix is complete, run some sanity checks: ----8<---- $ tla tree-lint $ tla what-changed * looking for haesslich@zork.net--projects/lnx-bbc--uglification-project--0.1--base-0 to compare with * comparing to haesslich@zork.net--projects/lnx-bbc--uglification-project--0.1--base-0 M CREDITS ----8<---- 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. ----8<---- $ 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 ----8<---- 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. ----8<---- $ 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 ----8<---- 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. ----8<---- $ cd .. $ rm -rf merge-copy/ $ cd lnx-bbc--uglification-project--0.1--base-0 $ tla update ----8<---- == 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: ----8<---- $ 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 ----8<---- 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. = More fun things you can do = == Cherry-picking changes == Suppose that you're the maintainer of lnx-bbc--research--0.0, and you just saw someone NUV a package in lnx-bbc--stable--2.1. The resulting revision for stable is now patch-69, and the current revision for research is patch-242. Since changesets are self-contained, you know that patch-69 contains only the stuff you want to bring over to your branch. Perhaps patch-68 was something that isn't applicable to the research codebase. Perhaps patches 30 through 68 are all judiciously back-ported features from the research branch. Well you can cherry-pick stable's patch-69 as a changeset you want to apply to the research branch. ----8<---- $ cd lnx-bbc--research--0.0--patch-242 $ tla replay lnx-bbc-devel@zork.net--gar/lnx-bbc--stable--2.1--patch-69 ----8<---- Resolve any conflicts and commit! You'll even have the stable developer's changelog entry in your commit log! == moving files == Arch has the "tla mv" command, which allows you to move a file from one place in a branch to another, retaining its revision history! == Speeding up remote operations == Arch uses SFTP as the remote protocol, and it's low-level enough that serious lag can be introduced while talking with gargoyle. To speed things up, you can create a local cache of individual files in the archive, otherwise known as a *library*. ----8<---- $ mkdir ~/.arch-library $ tla my-revision-library ~/.arch-library/ $ tla library-config --greedy ~/.arch-library/ $ tla library-add lnx-bbc-devel@zork.net--gar-autobuild/lnx-bbc--research--0.0 $ tla library-add lnx-bbc-devel@zork.net--gar-autobuild/lnx-bbc--stable--2.1 ----8<---- What you will now have is a greedy library that will automatically cache unpacked versions of all the files in those two branches you library-added. == Public mirrors == Occasionally you'll be partway into a project on a local branch, and you realize you need help or want to show your work to another developer. Arch to the rescue! ----8<---- $ tla make-archive --listing --mirror haesslich@zork.net--projects sftp://haesslich@zork.net/home/haesslich/public_html/arch $ tla archive-mirror haesslich@zork.net--projects ----8<---- Since this was mirrored to the arch subdir of haesslich's public_html on zork.net, he would direct people to do the following: ----8<---- $ tla register haesslich@zork.net--projects http://zork.net/~haesslich/arch $ tla get haesslich@zork.net--projects/lnx-bbc--uglification-project ----8<---- === The stable mirror, and the build's quarantine for it === The official anonymous mirror for lnx-bbc-devel@zork.net--gar is at http://www.lnx-bbc.com/arch Currently gargoyle runs two cron jobs that make mirrors. The first one is the script that mails recently checked-in patchsets to lnx-bbc-cvs. That one pushes all new commits to lnx-bbc--research up to the mirror each minute. The second is the autobuild job, which checks out lnx-bbc--stable and runs a complete build of it. If the build succeeds, the ISO goes up to http://lnx-bbc.com/builds/, a mail goes out about the success, and the version that was built is pushed to the mirror. If the build fails, nothing gets pushed and an error message goes to lnx-bbc-cvs. = Third party developers = Third-party developers have more flexibility and power under arch than they did with CVS. == Downloading from the read-only archives == ----8<---- $ tla register-archive http://www.lnx-bbc.com/arch $ tla get lnx-bbc-devel@zork.net--gar/lnx-bbc--stable--2.1 ----8<---- Then hack away. Feel free to branch off for your own changes as described earlier in this document. == Generating a changeset tarball for us to merge in == ----8<---- $ tla changes -o ,,my-illustrious-changes $ tar czvf my-illustrious-changes.tar.gz ,,my-illustrious-changes ----8<---- == Publishing your own archive for us to star-merge or replay from == If you branch off of the mirror and publish your branch as described elsewhere in this document, the LNX-BBC developers can then look at your entire revision history. This is far more powerful than receiving a changeset in e-mail, as we get to play with your archive. == Archive Syndication == We now have to keep track of development in various distributed branches. If you wish to have your archive's lnx-bbc branches appear on the planet page, the easiest way is for you to generate the rss out of cron. First: get from the scripts category. ----8<---- $ tla register-archive http://www.lnx-bbc.com/arch $ tla get scripts--gargoyle-bin ----8<---- (You can use your sftp archive for this as well) Then set up a cron job to run tla-rss.sh regularly with an appropriate archive and archzoom URL. If you do not wish to install archzoom on your system, lnx-bbc.com can be made to perform its functions (albeit inefficiently). ----8<---- */10 * * * * $HOME/bin/tla-rss.sh -n 25 -u http://psax.org/~dave/archzoom/archzoom.cgi dave@psax.org--projects/lnx-bbc > $HOME/public_html/rss/lnx-bbc.rss ----8<---- This will make an RSS file every ten minutes with the 25 most recent commmits from each lnx-bbc-- branch in Dave Barry's archive (provided you have registered dave@psax.org--projects). You can specify full version IDs to tla-rss.sh (to specify one branch in isolation), but to date you cannot give it category--branch without also specifying a version. Finally, come up with a code hobo (A.K.A. head) to appear by your commits. describes the process for turning a cropped head image into a hackergotchi using the GIMP: > I make four copies of the head, > layered atop one another. > At that point it looks like one head. > Then I blur the second layer down by about 5, > the next layer beneath that by about 10, > and the bottom one by about 15; > so you get a nice blur around the edge, > but the regular face image is on top. Make sure the image is a PNG that fades to a transparent background (with alpha channels and all) and that you scale it to 100x100. Also, if you would like your archive to have a special background image beneath the code hobo (such as we do for the official research and stable branches), please make sure that is scaled to 100x100 (though it can be in any format you like). == Locations of common developer archive mirrors == Nick Moffitt: "Yosemite" Sam Phillips: Nate "inkblot" Riffe: Dave "Psykoyiko" Barry: