How to use Piston to ease your upgrades

January 04, 2008

Piston (written by François Beausoleil) allows you to copy the content from a remote Subversion repository inside your own repository, while memorizing the remote revision in use at that time. It relies on a clever use of Subversion properties to memorize the remote revision number.

While copying the content once is already good in itself if you want to ensure you don’t depend on external repositories failures (eg: one repository for each of your Rails plugins for instance), the real benefit comes when you want to upgrade.

A couple of weeks later (or sooner!) you can ask Piston to update your local copy, then you will be able to commit the results (after running the tests and reviewing the changes), always in your repository.

Can it make my life better?

More and more applications need to be deployed along with some plugins to get specific behaviours.

Using Piston in that context you can:

keep a copy of a precise revision of these applications in your repository
keep a copy of each plugin in your repository as well (usually under a plugins folder)
tweak (modify/commit) each part if needed
upgrade each part only when you want to

Once you are done with it, you don’t have to worry about losing your deployment folder, and upgrades become much easier, as everything is under control.

How to use it, roughly?

Here’s a series of commands — that should give you the idea:

# install piston
gem install piston

# import the current mephisto trunk
# (current folder should be a svn working copy)
piston import http://svn.techno-weenie.net/projects/mephisto/trunk mymephisto

# commit this in our repository
svn commit -m "Piston import mephisto rev xxxx" mymephisto

# import a sitemap plugin
piston import http://svn.exdolo.com/projects/plugins/mephisto_sitemap/trunk \
  mymephisto/vendor/plugins/mephisto_sitemap

# commit this as well
svn commit -m "Piston import sitemap plugin rev xxxx" \
  mymephisto/vendor/plugins/mephisto_sitemap

# a few weeks later, update mephisto
piston update mymephisto

# review the changes, launch the tests, then commit
svn commit -m "Piston updated mephisto to rev yyyy" mymephisto

One caveat is that error messages in Piston can be hard to understand in some cases. I advise you to commit your modifications then run a svn update prior to calling piston update if you meet any issue.

Can I use it outside of Mephisto or Typo?

Definitely. If you write regular Rails applications, you can use Piston to handle all the Rails plugins for which you need to track the trunk. I’ve used Piston outside Rails on a Datawarehouse project with ActiveWarehouse-ETL.

Combine Piston, CruiseControl.rb and Capistrano and you get a robust development factory.