annotate vendor/plugins/engines/generators/plugin_migration/USAGE @ 929:5f33065ddc4b redmine-1.3

Update to Redmine SVN rev 9414 on 1.3-stable branch

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
    
      Engines.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.