Add Mina v0.2.0 upgrade notes.

See mina-deploy/mina#5, mina-deploy/mina#39, mina-deploy/mina#27, among others.

source/upgrading.md

@@ -0,0 +1,142 @@
+---
+title: Upgrading notes
+order: 20
+group: Misc
+---
+
+## Upgrading to v0.2.0
+
+Mina v0.2.0 is backwards-compatible, except for the deprecated
+`:revision` setting (which wasn't widely used anyway). However, Mina 0.2.0 adds
+new features and conveniences that may make it easier to
+implement tasks you're already doing.
+
+### New default script
+
+The new default deploy script generated by `mina init` has been improved to add
+more helpful comments to get you started. While not really necessary, try doing
+`mina init` *in an empty directory* to see the new default script.
+
+### RVM support
+
+The previous recommendation was to make your `~/.bashrc` load RVM. This was a
+little problematic: in Ubuntu systems, RVM wasn't always loaded because
+`.bashrc` wasn't loaded entirely in interactive shells. Also, some people prefer
+to load RVM in `~/.bash_profile`.
+
+To use RVM on Mina 0.2, make a task called `:environment` and from there, invoke
+`rvm:use[RUBY_VERSION@GEMSET]` like so:
+
+    # config/deploy.rb
+    require 'mina/rvm'
+
+    task :enviroment do
+      invoke :'rvm:use[ruby-1.9.2@default]'
+    end
+
+    task :deploy => :environment do
+      ...
+      # continue as usual
+      ...
+    end
+
+You do not need to create an `.rvmrc` file, although it is supported. In fact,
+as `.rvmrc` files are usually environment-specific, this practice is
+discouraged.
+
+A sample configuration can be seen by creating a new project using `mina init`
+(see ["New default script"](#new_default_script) section above).
+
+### rbenv support
+
+Mina v0.2 also features rbenv support. Like in RVM, older solutions of loading
+rbenv in `~/.bashrc` will continue to work, however you're recommended to use
+the new `rbenv:load` task.
+
+    # config/deploy.rb
+    require 'mina/rbenv'
+
+    task :enviroment do
+      invoke :'rbenv:load'
+    end
+
+    task :deploy => :environment do
+      ...
+      # continue as usual
+      ...
+    end
+
+Be sure to commit your `.rbenv-version` file in your project repository.
+
+### Git: removed the :revision setting
+
+The `:revision` setting has been removed in Mina v0.2.0. This used to allow you
+to deploy any given Git branch, tag, or commit.
+
+It has now been superceded by the `:commit` and `:branch` settings. To deploy a
+branch, set the `:branch` setting:
+
+    set :branch, 'master'
+
+And to deploy a given commit, set the `:commit` setting:
+
+    set :commit, '2f19299a'
+
+The reason for this change is that Git deploys are now optimized to be much
+faster when branches are specified.
+
+### Git: the default branch is now 'master'
+
+In Mina v0.1.x, the default deploy behavior is to deploy whatever the current
+commit is in your Git working repository.
+
+In 0.2.0, the default is now the `master` branch. To change this, change the
+`:branch` setting:
+
+    set :branch, 'deploy'
+
+### The 'deploy:link_shared_paths' task
+
+The `deploy:link_shared_paths` task has been existing since Mina v0.1.x, but was
+not documented.
+
+To make certain directories/files shared between different releases, first
+specify them in the `:shared_paths` setting:
+
+    set :shared_paths, ['log', 'config/database.yml']
+
+And link them in your deploy script by invoking `deploy:link_shared_paths`:
+
+    task :deploy => :environment do
+      deploy do
+        invoke :'git:clone'
+        invoke :'deploy:link_shared_paths'
+        ...
+        ...
+      end
+    end
+
+### New ':environment' task convention
+
+Mina introduces a new recommended convention of defining an `:environment` task
+to do initializations used for every command.
+
+It is often used to load RVM or rbenv so that it will be available in `mina
+deploy`, `mina rake[db:migrate]`, and other similar tasks.
+
+Define the task in your deploy script like so:
+
+    task :environment do
+      invoke :'rbenv:load'
+    end
+
+Then make the deploy task *depend* on it:
+
+    task :deploy => :environment do
+      ...
+    end
+
+This instructs Rake (or rather, Mina) to load the `:environment` task before
+deploying.
+
+This is entirely optional, but highly recommended.