README

Path: README
Last Update: Wed Mar 23 10:23:25 EST 2005

Fast Change Set Tool

FastCST (pronounced "fascist") is a change set tool I created to experiment with ideas in change management, distributed development, and alternatives to existing tools. The motto for FastCST is:

"Distribute like an anarchist, but accept like a fascist."

Current Features

FastCST supports an amazing amount of functionality for something I started just before March 2005. What you’re looking at is basically four months of work which says so much for Ruby.

The current laundry list of features are:

  * Complete changesets that are very simple by design and encode complete
    cohesive changes.
  * Extensible meta-data for changesets.
  * A simple to use repository that should be easy for any other language to read.
  * All revisions are uniquely identified by a UUID to avoid clashing.
  * Ability to undo any applied revision.
  * You can publish your repository to an FTP site efficiently.
  * Anyone can download the latest revisions from an FTP or HTTP site.
  * Transaction oriented operation.
  * Remarkably fast operation considering there's been no optimization done.
  * Send/receive changesets through e-mail including human readable meta-data.
  * A reasonable shell prompt so you don't have to type 'fcst' in front of everything.
  * A working plugins feature letting you implement your own commands, with an example
    command that creates release archives.
  * Ability to attach external files to distribute with your changesets (not tested much).
  * Disposition references so you can reference bug trackers, web sites, mailing list posts, etc.
  * 95% pure Ruby.
  * A unique delta algorithm that uses suffix arrays and produces smaller deltas than most other
    delta algorithms without sacrificing speed much.
  * A painstakingly consistent command interface with extensive help for each option.

Missing Features

There’s still quite a lot of stuff missing that I want to put into FastCST, but these are the big ones that it needs before it’s useful:

  * Merging is still not implemented.  This is the big one.  Without it the tool is next to
    useless.
  * Recovering individual files from the repository.  This should be a piece of cake.
  * Better protections against stupidity (like doing an undo after making changes).
  * The ability to "test" a revision, which applies it temporarily and then lets you kick
    it out without much hassle.
  * Better security protections like not using YAML for the journal file or somehow restricting
    what objects can be loaded (that thing is like giving a toddler a shot-gun).
  * Digitally signed and verified revisions so people can confirm who sent the revision.

Some of the things I’d like to implement are:

  * Using the built in suffix arrays to create a super fast stored index which programmers
    can search.
  * Connecting with FAM or Dazuko to let FastCST track your actions and warn about bad stuff.
  * Flexible command aliasing that lets you create alternative commands.
  * A better text UI that doesn't spew tons of crap to the screen you really don't care about.
  * Using WEBrick to easily share your repository.
  * Using mDNS to let people quickly and painlessly find repositories and other developers.
  * A nice static-only web interface that is generated and published during the publish command.
  * Hooking into DamageControl and the RSCM library.

If you have any suggestions for these or for other features you want then go ahead and contact me at zedshaw AT zedshaw DOT com.

Security Warnings

DO NOT ACCEPT CHANGESETS FROM PEOPLE YOU DO NOT KNOW. Since there’s no digital signature capabilities this means nobody except yourself. The reason why is because there are many places whe YAML is used, but YAML doesn’t provide a mechanism for restricting what can be loaded when unmarshalling Ruby structures. It would be no problem for someone to create a meta-data or journal file with a bit of code to destroy your world.

Another really big caution is please don’t use this thing on any source you feel is really important. It is still mostly ALPHA stage so there’s a very good chance that you’ll destroy your world if you use it.

Finally, it uses POP3 and FTP with bare passwords. This is mostly because I’m not sure how to get the Net::POP and Net::FTP stuff to use APOP and/or SSL. For the most part I’m just tunneling the protocols through SSH to my servers.

License

Copyright (C) 2004-2005 Zed A. Shaw

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

Building

The script that does everything is called "fcst", and the Rakefile is setup to build a completely stand-alone version. This is the version that you can run with only a basic ruby 1.8 install rather than installing all the files in your Ruby directories.

Building the fcst script this way requires simply typing "rake" in the source directory. When the build is done you’ll have a single ruby script in build/fcst.

Debian Notes

The build has been tested on ArchLinux and Debian, but to get it to build or run under Debian you need to make sure the following packages are installed:

  * libruby1.8
  * libzlib-ruby1.8
  * libyaml-ruby1.8
  * rake
  * ruby1.8-dev
  * libtest-unit-ruby1.8

Even then rake will fail because it can’t find the "testrb" stuff (which I have no idea where to find). This means that to build under Debian you need to do:

  1. rake compile
  2. rake tar

Which will skip the test target and just build the tar2rubyscript. A better approach for Debian is probably to use the standard setup.rb file that is included.

Installing

You can also "install" the fcst script in the normal ruby way using the setup.rb script. This installs the required libraries in your Ruby installation’s directories and thus requires root access.

The first thing you need to do is go into the software/rubymail-[version] directory and install RubyMail. Then installing is done with these commands:

 1. ruby setup.rb config
 2. ruby setup.rb setup
 3. sudo ruby setup.rb install

I prefer to use the sudo command, but you may use su instead.

When this is finished you’ll have the fcst script installed in your usual PATH and you’ll be able to run it like any other command.

Please refer to the section above on Debian since you still need to manually install quite a few packages.

Getting Started

FastCST is designed to be easy to use without restricting your ability to get stuff done. This means that most commands are very simple and follow a consistent pattern of operation with extensive help. It also means that, if you don’t like a command or need an additional feature then you can easily write your own.

The fcst script has two modes of operation:

 * shell mode -- This lets you run commands in a small little shell so that
   you don't have to keep typing 'fcst' before you do things.
 * command line mode -- You can also just put the command after the fcst
   script in your normal shell and it will run it directly.

The current shell is very primitive and doesn’t support readline or many other nice features.

If you want to get a list of commands then type ‘help’. It actually isn’t a command, but the error message for giving an invalid command is to print a list of all the commands available.

Available Commands

FastCST currently supports the following commands:

 * abort -- Aborts any currently in-process revision
 * apply -- Applies a child revision to the current revision
 * attach -- Attaches a file to the current in-process revision
 * begin -- Starts a new in-process revision
 * disp -- Adds a "disposition" reference to the in-process revision
 * env -- Lists, searches, sets, and deletes environment variables
 * finish -- Finalizes an in-process revision
 * get -- Gets the latest published revisions from a URL
 * init -- Sets up a new .fastcst repository in the current directory
 * list -- Let's you list revisions and your current revision path
 * log -- Adds a log line to the in-process revision (think Change Log)
 * publish -- Publishes your repository to an FTP site so others can use get
 * read -- Reads your "pending revision inbox" which contains received revisions
 * recv -- Receives revisions from a POP3 account and stores them for read
 * send -- Sends a chosen revision to a chosen person
 * show -- Shows information about a revision, or the in-process revision
 * status -- Gives a quick status of the current state of things
 * undo -- Rolls back the most recent apply

All commands take only switched arguments, no positional arguments. This is done for consistency, but it can be annoying. I’m looking into something else in the future, but feel free to suggest something or tell me you actually do like it.

Your First Repository

FastCST uses a "project local" repository design. This means that, rather than keeping everything in one master directory, it creates one directory for each project. The directory is called .fastcst and simple sits at the top of your source files.

What we’re going to do is actually get the latest version of FastCST using fcst. Make sure you’ve downloaded the script or built your own and then do this:

  1.  Create an empty directory and cd into it.
  2.  Run fcst
  3.  > init -e <your e-mail> -n <your name> -p fastcst
  4.  > get -u http://www.zedshaw.com/fastcst/repository
  5.  > list
  6.  > show -r root
  7.  > apply -r root

You now have the root revision of the FastCST stuff. The list and show stuff isn’t necessary, just a good idea so you don’t apply something that will cause you damage.

One current limit of fastcst is that when you get a remote repository it doesn’t ask you to apply all the revisions so you can sync up. I’m holding off on that feature until I get the merging algorithm done. Until then, feel free to apply the patches and play with the apply/undo stuff.

Other Things To Try

Here’s some other stuff for you to try out:

 1.  You do not need to have an empty directory to put files under fcst control.
 2.  Make a changeset by using begin/finish.  You can run begin, make some changes, and then
     run finish to create the revision.
 3.  Most commands that take a -r also take a -i so you can be specific about which revision
     to use.  Revision names are mostly just for weak humans who can't handle uuids.
 4.  Use list, show, and status religiously to figure out what's going on.
 5.  You can easily send a revision to someone else.  Use send to give them one, and then
     recv to get them from a POP3 account.  It works like e-mail where they are downloaded,
     and then you use 'read' to pick which ones you really want added to your repository.
 6.  Most commands will look for settings in the environment and use them as defaults.
     Try running a command without parameters and read the lines that talk about not finding
     a setting in the environment.  For example, recv will look for 'POP3 Host' so you can
     do "env -s 'POP3 Host' -v mail.myserver.com:110" and it will never bug you again.  If you
     need to use a different one temporarily, then specifying the option will override the
     environment setting.
 7.  If you've got an FTP server and web server to play with, then you can try the publish/get
     commands.
 8.  All commands take a -h option so you can get extensive help.

The only other cool thing you might want to experiment with writing your own commands.

Writing Your Own Commands

I never understand why programmer tools are wildly extensible. It’s in our blood to extend stuff for our needs, and yet most of the big tools we use are horribly inflexible. I decided right from the start that users (programmers) should be able to extend FastCST in any way they want without a lot of hassle. This decision is proving so useful that I’m imagining all sorts of useful things I can do with it.

Right now you can implement your own commands in Ruby which will function just like the ones that are included with fcst by default. Actually, the only difference between your commands and the default ones is location. Otherwise they are implemented exactly the same.

I’ve included a command I’ve been using in the file tools/release.rb which I use to make source release archives. To use it you simply have to copy it into your .fastcst/plugins directory and then run it from the fcst shell or command line. It will package a release tar.bz2 in the /tmp directory using tar that is named after your project and current revision.

Implementing a command involves the following steps:

  1.  Put everything in a file named after the command (release.rb)
  2.  require 'fastcst/command'
  3.  Create a class with the name of the command followed by Command (like ReleaseCommand).
  4.  Make it inherit from Command (like ReleaseCommand < Command).
  5.  Implement the initialize method, making sure you call the super(argv, []).  If
      you want command line arguments then just fill in the second argument like other commands.
  6.  Implement a validate method that uses the Command#valid? methods to check input.  It
      MUST return the @valid value (or some other true/false indicator of success).
  7.  Implement a run method that does it's stuff.
  8.  Finally, but the file in the .fastcst/plugins directory.

There’s plenty of examples available since all of the commands are implemented just like this. You‘ll most likely want to take a look at the Repository::Repository class and how most other commands use it.

More Detailed Documentation

This README just gives you some quick advice to get you started. Better documentation is available at www.zedshaw.com/projects/fastcst including the full API documentation (which is also in doc/rdoc), tutorials, and several other nice things.

Reporting Bugs

Feel free to contact me at zedshaw AT zedshaw DOT com with any bug reports you have. You may also find the latest release information at www.zedshaw.com/projects/fastcst as well as contact me on irc.freenode.org in the ruby or rubyonrails channel.

[Validate]