parlement 0.10 → 0.11

data/vendor/plugins/engines/README

@@ -1,414 +1,62 @@
-= Welcome
+The engines plugin enhances Rails' own plugin framework, making it simple to share controllers, helpers, models, public assets, routes and migrations in plugins.
 
-This document gives an overview of how the Engines mechanism works within a Rails environment. In most cases the code below is just an example. For more information or documentation, please go to http://rails-engines.org.
+For more information, see http://rails-engines.org
 
-== Background
+= Using the plugin
 
-Rails Engines are a way of dropping in whole chunks of functionality into your
-existing application without affecting *any* of your existing code. The could also be described as mini-applications, or vertical application slices - top-to-bottom units which provide full MVC coverage for a certain, specific application function.
+With engines 1.2, no extra configuration in environment.rb is required. Having the plugin installed will automatically enable sharing of code within <tt>plugin/app/</tt> directories. Developers should be aware that the <tt>config.plugins</tt> parameter can be used to control plugin load order, if this is important for your application.
 
-As an example, the Login Engine provides a full user login subsystem, including: 
-* controllers to manage user accounts; 
-* helpers for you to interact with account information from other 
-  parts of your application; 
-* the model objects and schemas to create the required tables; 
-* stylesheets and javascript files to enhance the views; 
-* and any other library files required.
+=== config.plugins
 
-Once the Rails Core team decides on a suitable method for packaging plugins, Engines can be distributed using the same mechanisms. If you are developing engines yourself for use across multiple projects, linking them as svn externals allows seamless updating of bugfixes across multiple applications.
+With Rails 1.2, the <tt>config.plugins</tt> list can be used to specify the order in which plugins are loaded. It's recommended (although not required) that you load the engines plugin first, and any other plugins later. The engines plugin enhances Rails' processing of <tt>config.plugins</tt> for occasions where you only care about the order of a small selection of your application's plugins. For instance, if you want to load +engines+ first, and anything else afterwards, then
 
-
-
-
-
-= Edge Engines
-
-If you are using Edge Rails (an SVN copy of Rails, rather than an 'official' release), there are several MASSIVELY IMPORTANT issues that you need to bear in mind.
-
-Firstly, you are using an unstable version of Rails, so it is possible that things will break. We work hard to keep the Engines plugin up to speed with the changes in Rails at the bleeding edge, but sometimes significant parts of Rails change it WILL cause problems. This is the price of using the bleeding edge. Since edge is synonymous for unstable, the version of the Engines plugin which is compatible with Edge Rails is kept separate from the official release. Please ensure that you have used SVN to get your engines plugin from
-
-  http://svn.rails-engines.org/engines/trunk
-  
-The normal 'script/plugin install engines' will NOT get you this version.
-
-Secondly, you NEED to tell the engines plugin if you expect it to perform with Edge behaviour. This is done by adding the following lines at the *very top* of environment.rb (yes, the VERY TOP)
-
-  module Engines
-    CONFIG = {:edge => true}
-  end
-
-This will set the plugin to work with Edge Rails, rather than expecting an official release.
-
-If you are having problems, please try and contribute a bug report if you can so we can improve the plugin and keep up to speed with Rails' bleeding edge. Your input is *absolutely crucial* to this. If you're not comfortable with tracking down bugs in Rails' and Engines' internal code, there is a test application available at
-
-  http://svn.rails-engines.org/applications/engines_test
+  config.plugins = ["engines", "*"]
   
-which contains an array of tests that might help you (and us) pinpoint where the issue is. Please download this application and consult the README for more information.
-
-Finally, please don't forget about our website and mailing lists. More information here:
-
-  http://rails-engines.org
+will ensure that engines is loaded first, and everything else (in whatever order Rails chooses) afterwards.
 
+== Better plugins
 
+In addition to the regular set of plugin-supported files (lib, init.rb, tasks, generators, tests), plugins can carry the following when the engines plugin is also installed.
 
 
+=== Controllers, Helpers, and Views
 
+Include these files in an <tt>app</tt> directory just like you would in a normal Rails application. If you need to override a method, view or partial, create the corresponding file in your main <tt>app</tt> directory and it will be used instead.
 
+* Controllers & Helpers: See Engines::RailsExtensions::Dependencies for more information.
+* Views: See Engines::RailsExtensions::Templates for more information.
 
-= Using the Engines plugin itself
+=== Models
 
-There are a number of features of the Engines plugin itself which may be useful to know:
+Model code can similarly be placed in an <tt>app/models/</tt> directory. Unfortunately, it's not possible to automatically override methods within a model; if your application needs to change the way a model behaves, consider creating a subclass, or replacing the model entirely within your application's <tt>app/models/</tt> directory. See Engines::RailsExtensions::Dependencies for more information.
 
+=== Routes
 
-=== Engines.log
-The Engines plugin comes with its own logger, which is invaluable when debugging. To use it,
-simply call
-
-  Engines.create_logger
-  
-Two optional arguments may be passed to this method:
-
-  Engines.create_logger(<io>)
-  
-Would set the outputter to the logger to the given IO object <io>. For example, this could be STDERR or STDOUT (the default). The second argument is the logger level:
-
-  Engines.create_logger(STDOUT, Logger::INFO)
-  
-The logger can be accessed using either of the following:
+Include your route declarations in a <tt>routes.rb</tt> file at the root of your plugins, e.g.:
 
-  Engines.log.[debug|info|whatever] "message"
-  Engines.logger.[debug|info|whatever] "message"
+  connect "/my/url", :controller => "some_controller"
+  my_named_route "do_stuff", :controller => "blah", :action => "stuff"
+  # etc.
   
-... essentially it's a Logger object. It's worth noting that if you *don't* create a logger, calls to Engines.log will just be swallowed without a sound, making it very very easy to completely silence Engine logging.
-
-
-=== Engines.config(:root)
+You can then load these files into your application by declaring their inclusion in the application's <tt>config/routes.rb</tt>:
 
-By default, the Engines plugin expects to be starting Engines from within RAILS_ROOT/vendor/plugins. However, if you'd like to store your engines in a different directory, add the following line *before* any call to Engines.start
+  map.from_plugin :plugin_name
 
-  Engines.config(:root, "/path/to/your/directory", :force)
+See Engines::RailsExtensions::Routing for more information.
   
-  
-=== Rake Tasks
+=== Migrations
 
-The engines plugin comes with a number of handy rake tasks:
+Migrations record the changes in your database as your application evolves. With engines 1.2, migrations from plugins can also join in this evolution as first-class entities. To add migrations to a plugin, include a <tt>db/migrate/</tt> folder and add migrations there as normal. These migrations can then be integrated into the main flow of database evolution by running the plugin_migration generator:
 
-  # display version information about the engines subsystem
-  rake engines:info 
-  
-  # migrate engines' database schemas in a controlled way
-  rake db:migrate:engines
+  script/generate plugin_migration
   
-  # generates full documentation for all engines
-  rake doc:engines      
-  
-There are more, but you'll have to discover them yourself...  
-
-
-== More information
-
-For more information about what you can do with the Engines plugin, you'll need to generate the documentation (rake plugindoc), or go to http://rails-engines.org. Good luck!  
-
-
-
-
-
-
-
-
-= Quickstart
-
-=== Gentlemen, Start your Engines!
-
-
-Here's an *example* of how you might go about using Rails Engines. Please bear in mind that actual Engines may differ from this, but these are the steps you will *typically* have to take. Refer to individual Engine documentation for specific installation instructions. Anyway, on with the show:
-
-1. Install the Rails Engines plugin into your plugins directory. You'll probably need to accept the SSL certificate here for the OpenSVN servers. For example:
-
-    $ script/plugin install engines
-
- or
-
-    $ svn co http://svn.rails-engines.org/plugins/engines <MY_RAILS_APP>/vendor/plugins/engines
-
-2. Install your engine into the plugins directory in a similar way.
-
-3. Create the RDoc for the engines plugin and for your engines so you know what's going on:
-
-     $ rake doc:plugins
-     $ rake doc:engines
-
-4. Initialize any database schema provided. The Engine may provide Rake tasks to do this for you. Beware that accepting an Engine schema might affect any existing database tables you have installed! You are STRONGLY recommended to inspect the <tt>db/schema.rb</tt> file to see exactly what running it might change.
-
-5. Add configuration to <tt>environment.rb</tt>:
-   e.g.
-
-      # Add your application configuration here
-      module MyEngine
-        config :top_speed, "MegaTurboFast"
-      end
- 
-      Engines.start :my_engine
-
-6. Run your server!
-
-      $ script/server
-
-
-
-
-= Building an Engine
-
-Here's a sample rails application with a detailed listing of an example engines as a concrete example:
-
-  RAILS_ROOT
-    |- app
-    |- lib
-    |- config
-    |- <... other directories ...>
-    |- vendor
-        |-plugins
-            |- engines               <-- the engines plugin
-            |- some_other_plugin 
-            |- my_engine             <-- our example engine
-                  |- init_engine.rb
-                  |- app
-                  |     |- controllers
-                  |     |- models
-                  |     |- helpers
-                  |     |- views
-                  |- db
-                  |- tasks
-                  |- lib
-                  |- public
-                  |     |- javascripts
-                  |     |- stylesheets
-                  |- test
-
-
-The internal structure of an engine mirrors the familiar core of a Rails application, with most of the engine within the <tt>app</tt> subdirectory. Within <tt>app</tt>, the controllers, views and model objects behave just as you might expect if there in the top-level <tt>app</tt> directory.
-
-When you call <tt>Engines.start :my_engine</tt> in <tt>environment.rb</tt> a few important bits of black magic voodoo happen:
-* the engine's controllers, views and models are mixed in to your running Rails application; 
-* files in the <tt>lib</tt> directory of your engine (and subdirectories) are made available 
-  to the rest of your system
-* any directory structure in the folder <tt>public/</tt> within your engine is made available to the webserver
-* the file <tt>init_engine.rb</tt> is loaded from within the engine - just like a plugin. The reason why engines need an init_engine.rb rather than an init.rb is because Rails' default plugin system might try and load an engine before the Engines plugin has been loaded, resulting in all manner of badness. Instead, Rails' skips over any engine plugins, and the Engines plugin handles initializing your Engines plugins when you 'start' each engine.
-
-From within <tt>init_engine.rb</tt> you should load any libraries from your <tt>lib</tt> directory that your engine might need to function. You can also perform any configuration required.
-
-=== Loading all Engines
-
-Calling either Engines.start (with no arguments) or Engines.start_all will load all engines available. Please note that your plugin can only be *automatically* detected as an engine by the presence of an 'init_engine.rb' file, or if the engine is in a directory named <something>_engine, or <something>_bundle. If neither of these conditions hold, then your engine will not be loaded by Engines.start() (with no arguments) or Engines.start_all().
-
-
-
-
-
-
-
-= Configuring Engines
-
-Often your engine will require a number of configuration parameters set, some of which should be alterable by the user to reflect their particular needs. For example, a Login System might need a unique Salt value set to encrypt user passwords. This value should be unique to each application.
-
-Engines provides a simple mechanism to handle this, and it's already been hinted at above. Within any module, a new method is now available: <tt>config</tt>. This method creates a special <tt>CONFIG</tt> Hash object within the Module it is called, and can be used to store your parameters. For a user to set these parameters, they should reopen the module (before the corresponding Engines.start call), as follows:
-
-  module MyModule
-    config :some_option, "really_important_value"
-  end
-  Engines.start :my_engine
-
-Because this config value has been set before the Engine is started, subsequent attempts to set this config value will be ignored and the user-specified value used instead. Of course, there are situations where you *really* want to set the config value, even if it already exists. In such cases the config call can be changed to:
-
-  config :some_option, "no_THIS_really_important_value", :force
-
-The additional parameter will force the new value to be used. For more information, see Module#config.
-
-
-
+This will produce a migration in your application. Running this migration (via <tt>rake db:migrate</tt>, as normal) will migrate the database according to the latest migrations in each plugin. See Engines::RailsExtensions::Migrations for more information.
 
-= Tweaking Engines
 
-One of the best things about Engines is that if you don't like the default behaviour of any component, you can override it without needing to overhaul the whole engine. This makes adding your customisations to engines almost painless, and allows for upgrading/updating engine code without affecting the specialisations you need for your particular application.
+=== More powerful Rake tasks
 
+The engines plugin enhances and adds to the suite of default rake tasks for working with plugins. The <tt>doc:plugins</tt> task now includes controllers, helpers and models under <tt>app</tt>, and anything other code found under the plugin's <tt>code_paths</tt> attribute. New testing tasks have been added to run unit, functional and integration tests from plugins, whilst making it easier to load fixtures from plugins. See Engines::Testing for more details about testing, and run
 
-=== View Tweaks
-These are the simplest - just drop your customised view (or partial) into you <tt>/app/views</tt> directory in the corresponding location for the engine, and your view will be used in preference to the engine view. For example, if we have a ItemController with an action 'show', it will (normally) expect to find its view as <tt>report/show.rhtml</tt> in the <tt>views</tt> directory. The view is found in the engine at <tt>/vendor/engines/my_engine/app/views/report/show.rhtml</tt>. However, if you create the file <tt>/app/views/report/show.rhtml</tt>, that file will be used instead! The same goes for partials.
-
-
-=== Controller Tweaks
-You can override controller behaviour by replacing individual controller methods with your custom behaviour. Lets say that our ItemController's 'show' method isn't up to scratch, but the rest of it behaves just fine. To override the single method, create <tt>/app/controllers/item_controller.rb</tt>, just as if it were going to be a new controller in a regular Rails application. then, implement your show method as you would like it to happen.
-
-... and that's it. Your custom code will be mixed in to the engine controller, replacing its old method with your custom code.
-
-
-=== Model/Lib Tweaks
-Alas, tweaking model objects isn't quite so easy (yet). If you need to change the behaviour of model objects, you'll need to copy the model file from the engine into <tt>/app/models</tt> and edit the methods yourself. Library code can be overridden in a similar way.
-
-
-
-
-
-
-
-
-
-= Public Files
-
-If the Engine includes a <tt>public</tt> directory, its contents will be mirrored into <tt>RAILS_ROOT/public/engine_files/&lt;engine_name&gt;/</tt> so that these files can be served by your webserver to browsers and users over the internet.
-
-Engines also provides two convenience methods for loading stylesheets and javascript files in your layouts: <tt>engine_stylesheet</tt> and <tt>engine_javascript</tt>.
-
-=== Engine Stylesheets
-
-  <%= engine_stylesheet "my_engine" %>
-
-will include <tt>RAILS_ROOT/public/&lt;engine_files&gt;/my_engine/stylesheets/my_engine.css</tt> in your layout. If you have more than one stylesheet, you can include them in the same call:
-
-  <%= engine_stylesheet "my_engine", "stylesheet_2", "another_one" %>
-
-will give you:
-
-    <link href="/engine_files/my_engine/stylesheets/my_engine.css" media="screen" rel="Stylesheet" type="text/css" />
-    <link href="/engine_files/my_engine/stylesheets/stylesheet_2.css" media="screen" rel="Stylesheet" type="text/css" />
-    <link href="/engine_files/my_engine/stylesheets/another_one.css" media="screen" rel="Stylesheet" type="text/css" />
-
-in your rendered layout.
-
-=== Engine Javascripts
-
-The <tt>engine_javascript</tt> command works in exactly the same way as above.
-
-
-
-
-
-
-
-
-
-= Databases and Engines
-
-Engine schema information can be handled using similar mechanisms to your normal application schemas.
-
-== CAVEAT EMPTOR!
-
-I.E. Big Huge Warning In Flashing Lights.
-
-PLEASE, PLEASE, PLEASE bear in mind that if you are letting someone
-ELSE have a say in what tables you are using, you're basically opening
-your application schema open to potential HAVOC. I cannot stress how
-serious this is. It is YOUR responsibility to ensure that you trust
-the schema and migration information, and that it's not going to drop
-your whole database. You need to inspect these things. YOU do. If you
-run these voodoo commands and your database essplodes because you
-didn't double double double check what was going on, your embarassment
-will be infinite. And your project will be skroo'd if the migration
-is irreversible.
-
-That said, if you are working in a team and you all trust each other,
-which is hopefully true, this can be quite useful.
-
-
-== Migrating Engines
-
-To migrate all engines to the latest version:
-
- rake db:migrate:engines
-
-To migrate a single engine, for example the login engine:
-
- rake db:migrate:engines ENGINE=login  (or login_engine)
-
-To migrate a single engine to a specific revision:
-
- rake db:migrate:engines ENGINE=login VERSION=4
-
-This:
-
- rake db:migrate:engines VERSION=1
-
-... will not work, because we felt it was too dangerous to allow ALL
-engines to be migrated to a specific version, since such versions
-might be incompatible.
-
-
-
-
-
-
-
-= Testing Engines
-
-The Engines plugin comes with mechanisms to help test Engines within a developer's own application. The testing extensions enable developers to load fixtures into specific
-tables irrespective of the name of the fixtures file. This work is heavily based on
-patches made by Duane Johnson (canadaduane), viewable at
-http://dev.rubyonrails.org/ticket/1911
-
-Engine developers should supply fixture files in the <engine>/test/fixtures directory
-as normal. Within their tests, they should load the fixtures using the 'fixture' command
-(rather than the normal 'fixtures' command). For example:
-
-  class UserTest < Test::Unit::TestCase
-    fixture :users, :table_name => LoginEngine.config(:user_table), :class_name => "User"
- 
-    ...
-
-This will ensure that the fixtures/users.yml file will get loaded into the correct
-table, and will use the correct model object class.
-
-Your engine should provide a test_helper.rb file in <engine>/test, the contents of which should include the following:
-
-  # Load the default rails test helper - this will load the environment.
-	require File.dirname(__FILE__) + '/../../../../test/test_helper'
-
-	# ensure that the Engines testing enhancements are loaded and will override Rails own
-	# code where needed. This line is very important!
-	require File.join(Engines.config(:root), "engines", "lib", "testing_extensions")
-
-	# Load the schema - if migrations have been performed, this will be up to date.
-	load(File.dirname(__FILE__) + "/../db/schema.rb")
-
-	# set up the fixtures location to use your engine's fixtures
-	Test::Unit::TestCase.fixture_path = File.dirname(__FILE__)  + "/fixtures/"
-	$LOAD_PATH.unshift(Test::Unit::TestCase.fixture_path)
-
-== Loading Fixtures
-
-An additional helpful task for loading fixture data is also provided (thanks to Joe Van Dyk):
-
-  rake db:fixtures:engines:load
-  rake db:fixtures:engines:load PLUGIN=login_engine
+  rake -T
   
-will load the engine fixture data into your development database.
-
-=== Important Caveat
-Unlike the new 'fixture' directive described above, this task currently relies on you ensuring that the table name to load fixtures into is the same as the name of the fixtures file you are trying to load. If you are using defaults, this should be fine. If you have changed table names, you will need to rename your fixtures files (and possibly update your tests to reflect this too).
-
-You should also note that fixtures typically tend to depend on test configuration information (such as test salt values), so not all data will be usable in fixture form.
-
-
-
-= LICENCE
-
-Copyright (c) 2006, James Adam
-
-The MIT License
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
+to see the set of rake tasks available.

data/vendor/plugins/engines/Rakefile

@@ -0,0 +1,14 @@
+require 'rake'
+require 'rake/rdoctask'
+
+task :default => :doc
+
+desc 'Generate documentation for the engines plugin.'
+Rake::RDocTask.new(:doc) do |doc|
+  doc.rdoc_dir = 'doc'
+  doc.title    = 'Engines'
+  doc.main     = "README"
+  doc.rdoc_files.include("README", "UPGRADING", "CHANGELOG", "MIT-LICENSE")
+  doc.rdoc_files.include('lib/**/*.rb')
+  doc.options << '--line-numbers' << '--inline-source'
+end

data/vendor/plugins/engines/UPGRADING

@@ -0,0 +1,93 @@
+= Upgrading from Engines 1.1.x to Engines 1.2.x
+
+
+The 1.2 release of the engines plugin represents a significant rewrite of the internals. Now less intrusive into the core frameworks, it's even simpler for plugin developers to make more flexible plugins than Rails typically allows.
+
+However, as a consequence of change, you may need to make some adjustments to your application to get the most benefit. These are outlined below:
+
+
+== In your application
+
+The following changes will affect code in applications which use the engines plugin
+
+=== Change the engine_schema table to plugin_schema
+
+Because the engines plugin now works universally for any Rails plugin, the table used to store migration information has been renamed appropriately. We can also play nicely with other plugin_migration implementations by supporting this convention.
+
+
+=== Rename RAILS_ROOT/public/engine_files to RAILS_ROOT/public/plugin_assets
+
+Similarly, any plugin can now share stylesheets, images and so on via an assets folder, so the destination within the main public directory has been renamed to reflect this. You can simply delete the RAILS_ROOT/public/engine_files directory; the new one will be generated the next time your application starts.
+
+
+=== The engine_image, engine_stylesheet and engine_javascript helpers have been replaced with enhanced versions of the normal Rails asset helpers
+
+Now, it's simple to include an image from any plugin, by adding a plugin key to the helper's options hash:
+
+  image_tag "image.png", :plugin => "my_plugin"
+
+A similar convention exists for stylesheets and javascript files. Additionally, the old behaviour of automatically including assets which match the "engine"'s name has been dropped - only the files you explicitly request are included.
+
+
+=== Engines.start is replaced with config.plugins
+
+Rails' native configuration object now includes an array for specifying which plugins are loaded, and in what order. The engines plugin enhances this feature with a "*" wildcard, so that you can load any order-sensitive plugins, and then the rest in any order.
+
+  config.plugins = ["engines", "some_plugin", "another_plugin", "*"]
+  
+It's worth noting that the engines plugin no longer needs to be specifically loaded first, so most people can happily ignore the config.plugins array without any problems.
+
+
+=== The "config" method for "engine"-style configuration is no longer loaded by default. 
+
+See below.
+  
+  
+=== Any "engines" type rake tasks are now "plugin" tasks.
+
+The following rake tasks are now provided by the engines plugin for operating on your application's plugins (whenever a task can operate on a single plugin, this can be controlled by specifying PLUGIN=<name> on the commandline):
+  
+  db:fixtures:plugins:load  # load fixtures from plugins. 
+  
+  test:plugins:units        # Run tests from within <plugins>/test/units
+  test:plugins:functional   # Run tests from within <plugins>/test/functional
+  test:plugins:integration  # Run tests from within <plugins>/test/integration
+  test:plugins              # Run all tests from within <plugins>/test/*
+
+  doc:plugins               # Run full rdoc against all source files within all plugins
+  doc:plugins:<plugin>      # Run full rdoc against all source files within the given plugin
+
+
+
+== In your "engine"-style plugins
+
+If you have developed or are using plugins that leverage engines enhancements, you need to be aware of the following changes in engines 1.2.
+
+=== init_engine.rb is no longer required
+
+Please now create init.rb files, just as you'd find in "normal" plugins. Remember - there's no such thing as "an engine" anymore.
+
+
+=== The "fixture" method for loading tests from arbitrary files
+
+Supporting this was just too difficult, and it seems like the combination of Rails' own lack of enhancements regarding this feature, along with the mind-shift against static fixtures, meant that it simply was too much work to continue to support.
+
+The only reason this mechanism originally existed was to support plugins which couldn't predict the names of the tables that models might be stored in. This is now a discouraged behaviour.
+
+
+=== Engines.current.version has changed its behaviour slightly.
+
+The engines plugin used to provide a simple way to store version information about plugins. This has now been superceded by including that information in an about.yml file, which any plugin can use.
+
+
+=== The "config" method is not included, by default.
+
+Where previously developers could use the "config" method to define configuration, this is now deprecated in favour of using mattr_accessor directly in the Module. However, if you still *need* to use the config method, it is included but must be explicitly required, probably near the top of environment.rb:
+  
+  require File.join(RAILS_ROOT, "vendor", "plugins", "engines",
+                    "lib", "engines", "deprecated_config_support")
+
+
+=== Public assets should now be stored in a subdirectory of your plugin called "assets", rather than "public".
+
+This clarifies the nature of this directory; it is not made public itself, but rather is a container for files which should be made accessible from the web.

data/vendor/plugins/engines/about.yml

@@ -0,0 +1,7 @@
+author: James Adam
+email: james.adam@gmail.com
+homepage: http://www.rails-engines.org
+summary: Enhances the plugin mechanism to perform more flexible sharing
+description: The Rails Engines plugin allows the sharing of almost any type of code or asset that you could use in a Rails application, including controllers, models, stylesheets, and views.
+license: MIT
+version: 1.2.0

data/vendor/plugins/engines/generators/plugin_migration/USAGE

@@ -0,0 +1,45 @@
+Description:
+  The plugin migration generator assists in working with schema additions 
+  required by plugins. Instead of running migrations from plugins directly,
+  the generator creates a regular Rails migration which will be responsible
+  for migrating the plugins from their current version to the latest version
+  installed.
+  
+  This is important because the set of application migrations remains an
+  accurate record of the state of the database, even as plugins are installed
+  and removed during the development process.
+
+Example:
+  ./script/generate plugin_migration [<plugin_name> <another_plugin_name> ...]
+
+  This will generate:
+
+    RAILS_ROOT
+      |- db
+          |-migrate
+              |- xxx_plugin_migrations.rb
+
+  which contains the migrations for the given plugin(s).
+  
+  
+Advanced Usage:
+
+There may be situations where you need *complete* control over the migrations
+of plugins in your application, migrating a certainly plugin down to X, and
+another plugin up to Y, where neither X or Y are the latest migrations for those
+plugins.
+
+For those unfortunate few, I have two pieces of advice:
+
+ 1. Why? This is a code smell [http://c2.com/xp/CodeSmell.html].
+ 
+ 2. Well, OK. Don't panic. You can completely control plugin migrations by
+    creating your own migrations. To manually migrate a plugin to a specific
+    version, simply use
+    
+      Rails.plugins[:your_plugin_name].migrate(version)
+      
+    where version is the integer of the migration this plugin should end
+    up at.
+    
+With great power comes great responsibility. Use this wisely.