10 Minute Guide

I figured the best way for people to play with FastCST as it is now is for them to go through something like a manual test case. This way I get free cheap labor and you get to do something completely mind-numbingly boring. Alright, I’ll try to make it not so boring, but don’t blame me if you would rather watch Desperate Housewives.

This introduction will cover some terms, run through an example of using FastCST, and then cover some advanced functionality. The whole process shouldn’t take more than 10-20 minutes including building and installing FastCST (assuming you actually read the instructions).

Getting The Gear

The simplest way to get started is to download the stand-alone single ‘fcst’ script and try running one of the included scripts. One was build on ArchLinux the other Debian. If neither of those work then download the release and follow the README instructions for installing it using the setup.rb script.

Some Fancy Words

Before you get started, there’s some words I’ll be using which you should be familiar with:

repository —This is effectively the “work” or “backup” directory that FastCST uses to store the data it needs. This directory sits at the top of your source and is named .fastcst so it is hidden under Unix.

sources —The sources are the files you’re managing under FastCST.

originals —FastCST keeps a backup of the last set of files you added to a revision in the .fastcst/originals directory.

changeset —A changeset is the set of three files that encode information needed to work with a revision. The term is used interchangeably with revision usually, but I’ll make sure to be specific when I need to talk about the actual changeset files.

revision —The name of a changeset when it’s stored in your repository.

id —A UUID (big number) used to uniquely identify a revision.

revision tree —Revisions are organized in a tree of parent/child relationship so that you can know which revision will reliably apply to another, and so you can determine history.

merge —Praying that changes someone else made will not break your build and cost you tons of money. Also the process by which you combine several changesets to make a new revision.

apply —Working a revision that’s a child of your current one so that you get the updates from the child.

undo —Reverses the apply process so that you are back where you started.

in-progress revision —A revision you are currently working on. These are started by the begin command and ended by the finish command. Some commands cannot run unless you are in-progress, and others will not run if you are.

That’s the extent of the terminology you would need to know for the moment. I’m actually working to reduce even that further in an attempt to simplify things further.

The next step is to try using FastCST in a series of situations.

Making Your First Changeset

Make sure you can run the fcst command without any problems. If you still have problems and you’ve read through the README then contact me at zedshaw at zedshaw dot com or on IRC in #ruby-lang on the irc.freenode.org servers.

We’re going to actually grab the FastCST source using the fcst command. Just do this:

mkdir fastcst

cd fastcst

fcst init -e (youremail) -n (your full name) -p fastcst

fcst get -u http://www.zedshaw.com/fastcst/repository

That should be it. Replace (youremail) and (your full name) with actual values, not fake ones. You’ll need your real e-mail address later. Next step is to use the apply command to move your currently empty repository to the latest 0.6.5 revision.

Applying Revisions

You currently have an empty source directory, but you need to be at the 0.6.5.1 revision. The way you do this right now is manually, but future versions will let you do this automatically. Just do the following:

fcst

> apply -r root

> apply -r 0.6.3

> apply -r 0.6.4

> apply -r 0.6.5

> list

> apply -r 0.6.5.1

> list

> status

The first thing to notice is that we just run fcst without any commands to get into shell mode. The shell mode is a very basic shell-like prompt so you can easily run commands without having to type “fcst” all the time. After that we just apply each revision in order, using an occasional list command to see what’s next.

A list command without any options (use -h to get help for it) will show you the current path of applied revisions, and then a list of children under this path. It similar to the ls command in your normal shell. At the end the status command should show that nothing has changed.

Kind of a pain, but you explicitly know what’s going on during the process, so you won’t be surprised if you suddenly get weird stuff. We’ll fix this huge path next using merging to make a new release.

Creating A New Release

So you don’t want people to have to do all that apply crap (which will go away in the near future). No problem, we’ll just make a new release that contains all those fixes and is a direct child of root. First thing we have to do is use undo and list to get back to the root revision.

> undo

> list (should show [ root/0.6.3/0.6.4/0.6.5 ] for path)

> ...

Just keep doing undo/list until the path shown by list says [ root ] and then stop. You are now at the root of the revision tree.

The next thing we want to do is create our new 0.6-release revision which will eventually contain all of these revisions in one snappy packaged revision. This is pretty simple:

> begin -r 0.6-release -p “Final 0.6 release”

> status

> show -c

> list

The begin command should tell you some simple stuff like the UUID of the revision. The status command should still show no changes, but the show command should dump information on your current in-progress revision. Finally, the list command will show you that you’re working on 0.6-release and you are at revision path [ root ] (which has 0.6.3 as a child).

Now that you’ve started a new we can merge “down the revision tree” to combine all the little 0.6 revisions into one final revision. This is again pretty simple using the merge command:

> merge -r 0.6.3

> list -r 0.6.3

> merge -r 0.6.4

> list -r 0.6.4

> merge -r 0.6.5

> list -r 0.6.5

> merge -r 0.6.5.1

> status

Each merge command should say there are no conflicts, and then ask if you want to go ahead an apply the revision. Each time you do it, you are basically modifying the 0.6-release you have in-progress. The list commands are basically showing you what children are under the revision you just merged. This lets you follow the path reliably, but you don’t have to do the listing if you don’t want (and you’re really brave).

What happens if you mess up and want to start over? You’ll want to use the abort -f command, which does a “full” (-f) abort completely abort any changes you made and put you back at the root revision (or whatever revision you started with before the begin command). The other option is to just fix it yourself manually.

It’s a good idea to get in the habit of doing a log command between each merge so that people know why you’re doing this. Notice I said “why” and not “what”, “how”, “where”, “who”, or “when”? All the other questions are answered by the meta-data that comes with each revision. Try doing a show -c command to see what is available already. What people really need is why you are doing this. What’s your motivation?

Another habit to get into is not mixing merging with making other changes like fixing bugs. This is totally up to taste, but I’ve found that when you mix bug fixes with merging it blends the bug fix into the merge making it hard to apply to other revisions. It also hides your real intent which is to merge other revisions into a new revision. Just some friendly advice from someone who’s had to deal with “moby patches” that we giant whales and impossible to decipher.

Now that you’ve made all your merges, you could make some additional changes if you like. One thing I try to do is run my clean process (rake clean ; ruby setup.rb clean) so that I’m not accidentally putting junk in my revisions. The revisions you have actually have this very problem, so I’m going to come up with a more automatic solution to the problem using Triggers.

Anyway, all you have to do now is run the finish command and you’re done. Use the usual list, status, and show commands to figure out what happened.

Next up is covering the different ways you can distribute your fancy new revision.

Distributing Changesets

FastCST supports three main ways of distributing revisions: e-mail, ftp+http, http only. Each has their advantages/disadvantages depending on what you need to do. I’ll be adding more secure methods in the near future as well.

Let’s say you just want to send this 0.6-release revision you created to a co-worker with very little fuss. You’ve got two choices depending on what kind of networking is available:

Send it to them using e-mail. This will depend on the size of the changeset you’re blasting at them (add about 30% for encoding), the type of e-mail access you have (requires POP3 to receive and SMTP to send), and how many revisions they need. The nice thing about e-mail is that it works nearly everywhere and goes through firewalls like mad.

Serve your repository straight to them using the embedded web server. This method is the easiest since it involves one command: serve. The embedded web server will only serve your changesets (nothing else). The current limitation with the serve command is that you can’t use your repository while you are serving it to someone. That should come pretty soon though.

The third method is where you use the publish command to publish your new repository changes to an FTP server which other can access using the get command (which will work with FTP or HTTP).

Introducing The Environment

The main problem with distributing your changes over the network is that it requires some amount of configuration. The serve and get commands don’t take much, but send, recv, read and publish take quite a few configuration options.

FastCST helps with this problem by letting you store common configuration options in the Environment. This is just a YAML file name env.yaml in the repository directory (.fastcst/env.yaml). You can search or modify the settings in this file using the env command. Let’s setup our default SMTP Host for the send command:

> env -s ‘SMTP Host’ -v yourhost:port

> env

Send, Recv, Read

Once you set the ‘SMTP Host’ environment variable, then you can just run the send command with the following options:

> send -r 0.6-release -t receiver@receiver.com

Once you send it to someone they will need to use the recv, and read commands to get them:

> recv -u username -p password -c pop3.host.com:110

> read

> apply -r 0.6-release

The recv command also uses environment variables ‘POP3 Host’ and ‘POP3 Username’ to make things even easier.

Serve and Get

The other method is to use the server and get commands to quickly sync a repository right out of your repository. This is handy if you just want to trade with someone else on your network real quick or if you want to get stuff onto another computer. It’s pretty simple. On the “master” computer, do this:

> serve

TADA! Your repository is now available to anyone else at http://yourhost:3040 (make sure you don’t add the trailing /). You can change the port with the -p option. One the host(s) you want to receive revisions on do:

> get -u http://yourhost:3040

Which is just like what you did previously to get the FastCST repository.

Publish

The other distribution method is to use an FTP server and the publish command. I’ll leave this to you to figure out.

Other Goodies

That’s pretty much all there is to using FastCST, and hopefully that’s all there ever will be to using it. There may be a refinement of the apply vs. merge concept (since they are nearly the exact same thing), but otherwise it’s pretty stable. You’ll probably want to play with some of the other commands that are available and please feel free to try and break things. I love bug reports.

Feel free to read the FAQ and learn about writing your own plugins.

Full List of Commands

You can also get this list by using the “help” or ? commands.

abort—Aborts an in-progress current revision

apply—Applies a child revision to this one (use list first)

attach—Attaches a file to the in-progress revision (experimental)

begin—Starts a new in-progress revision

disp—Adds a disposition line to the in-progress revision

env—Searches and updates the environment

finish—Finalizes an in-progress revision putting it in the repository

get—Gets revisions from someone else’s repository via a URL

index—Creates and searches a source content index (experimental)

init—Initializes a new repository in the current directory

list—Lists revisions and/or your current position in the tree (think ls)

log—Adds a log line to the in-progress revision

merge—Merges another revision to the in-progress revision

publish—Publishes your repository to an FTP site

read—Reads revisions out of your pending mail box (after a recv)

recv—Receives revisions from POP3 and puts them in your pending mail box (use read)

send—Sends a revision to someone else over SMTP

serve—Fires up an embedded web server so you can server your repository directly without FTP (read only)

show—Shows a particular revision or the current in-progress revision

status—Gives a quick or full (-f) status of the changes you’ve made and whether you’re in-progress

undo—Undoes the last apply. Use abort if you’re in-progress.