Transitioning to Autumn 3.0
This document will show you how to move your leaves from Autumn 2.0.x to Autumn 3.0. Fortunately, unlike the move from Autumn Leaves 1.0 to Autumn 2.0, this won’t be nearly as painful. Mostly it’s just moving some files around and renaming them, and updating your code for Facets 2.4 and DataMapper 0.9. But first…
Why should I bother upgrading to Autumn 3.0? Autumn 3.0’s primary advantage over 2.x is its better directory organization. Files have been moved around so that all of a leaf’s distributable files are under one directory. This makes it very easy to package up your leaf and distribute it to others. In addition, Autumn 3.0 resolves any namespace conflicts with 2.×. If you had two leaves with two different data models that had namespace issues because they shared table names, this is now a thing of the past. Finally, Autumn 3.0 brings Autumn leaves even closer to Ruby on Rails applications, with full MVC abstraction and ERb view templates.
Leaves have had their directory structures reorganized in Autumn 3.0. Follow the example leaf, Scorekeeper, to see how your leaf should be reorganized.
Firstly, create a new directory under leaves named after your leaf. The directory must have the same name as your leaf, in “snake_case”. Place your leaf’s Autumn::Leaf subclass file in that directory, and rename it controller.rb. This is your leaf’s controller. It acts as an intermediary between your data and its presentation.
Move the files in your leaf’s support subdirectory into your new leaf directory. DataMapper models should go a models subdirectory within your leaf’s directory. Support modules should go in a helpers subdirectory within your leaf’s directory.
If you have any custom leaf tasks in the tasks directory, move them into a tasks subdirectory within your leaf’s directory.
If you have any data files that you were storing in a data directory (or elsewhere), you can move it into a data directory within your leaf’s directory.
First off, you should rename the class in your controller.rb file to Controller. It’s no longer named after your leaf; the name of your leaf is now taken from the folder name (CamelCased). Generally, you won’t need to make any other changes to your controller. In the future you can consider moving some (or all) of your commands’ view code into separate ERb templates; see the README for more information.
Behind the scenes, however, there are a few things at work here. Firstly, all of your leaf’s code is being silently placed into a module named after your leaf. So even though you’ve just named your class Controller, it’s really YourLeaf::Controller. The same goes for your helpers and your models. That way, you can have multiple classes all called Controller, multiple models with the same name, or whatever you need.
Your helpers can remain largely the same. You can rename them, if you wish: It’s no longer required that the helper have the leaf name in it. So what was once YourLeafNetworkHelper can now just be NetworkHelper. Your helpers must still end with “Helper”, however.
Your models will need to be upgraded to DataMapper 0.9. This is a backwards-incompatible update, so your 0.3 models will not work under Autumn 3.0.
Consult the DataMapper 0.9 release notes for a crash course in how to move your models to 0.9. It covers most of what you need to know, but you may run into other issues, and be forced to consult the DataMapper API documentation or the source code itself to resolve them.
Although your models are being silently defined in a module named after your leaf, you can write DataMapper code as if they were top-level objects. The libs/datamapper_hacks.rb file contains some code to ensure that your code will work inside a module or outside.
Your season config files will remain largely the same. If you would like, you can create a config.yml file within your leaf’s directory and place leaf-specific directives there. These will be global to all instances of your leaf, but can be overriden by directives in the leaves.yml file.
If you’d like, you can shorten your database.yml syntax, taking advantage of a new feature in DataMapper 0.9. Instead of a hash of options, you can define your DB connection with a string of the format
adapter://username:password@host/database
You can leave out whatever information you don’t need to specify. For example, a typical PostgreSQL configuration on localhost might be postgres://localhost/my_database. This is much more concise than a hash.
The leaves.yml file is now optional. If you don’t have any options set for your leaves (or if they are set in each leaf’s config.yml file), you can go ahead and drop the file. Autumn will automatically instantiate each leaf in the leaves directory once.
Autumn 3.0 requires Facets 2.4 or better, and DataMapper 0.9.×. So go ahead and upgrade your gems to these versions.
Once you’ve finished all these tasks, your leaves should be good to go in Autumn 3.0. Be sure to put them through their paces to make sure they stand up to the new environment.