First pass at the upgrade guide for 1.x. (#154)

docs/1.x-upgrade.md

@@ -0,0 +1,137 @@
+# Moonshot 0.7.x to 1.x upgrade guide #
+
+There have been a lot of changes in the 1.x release that we're very
+excited about. However, we've taken this opportunity to make some
+serious changes that are not backwards compatible, hence the major
+version release.
+
+This guide serves as a listing of the major changes.
+
+## Moonfile, and the removal of Moonshot::CLI ##
+
+Thor was proving to be quite difficult to work with in the architecture
+we were trying to build. We've swapped it out for OptionParser. In
+addition, we no longer have a superclass that must be subclassed in
+your own file. Instead, we now ship a `moonshot` commandline tool with
+the Gem. This tool searches the directory hierachy for a `Moonfile.rb`
+file with the configuration for `Moonshot::Controller`, similar to the
+behavior of Bundler.
+
+An example of what this means:
+
+### Before: bin/environment derived from Moonshot::CLI ##
+```ruby
+class MyProject < Moonshot::CLI
+  self.application_name     = 'my-project'
+  self.artifact_repository  = S3Bucket.new('my-project-builds')
+  self.deployment_mechanism = CodeDeploy.new(asg: 'MyProjectASG')
+  self.build_mechanism      = Script.new('scripts/build.sh')
+end
+```
+
+### After: Moonfile.rb in project root ###
+```ruby
+Moonshot.config do |c|
+  c.app_name             = 'my-project'
+  c.artifact_repository  = S3Bucket.new('my-project-builds')
+  c.deployment_mechanism = CodeDeploy.new(asg: 'MyProjectASG')
+  c.build_mechanism      = Script.new('scripts/build.sh')
+end
+```
+
+## Plugin and CLI Extension auto-loading ##
+
+With the addition of Moonfile.rb, we've changed how plugin source and
+custom commands should be loaded.
+
+### Plugin Source auto-loading ###
+
+Any files located in `moonshot/plugins` ending in `.rb` will be loaded
+after the invocation of the `moonshot` CLI tool. These files can
+contain class defitions added as a plugin.
+
+For example:
+```ruby
+# moonshot/plugins/my_plugin.rb
+class MyPlugin
+  def pre_create
+    # ..
+  end
+end
+
+# Moonfile.rb
+Moonshot.config do |c|
+  # ...
+  c.plugins << MyPlugin.new
+end
+```
+
+We're hoping this layout allows better organization of Moonshot
+customizations within you project.
+
+### CLI Extensions and Moonshot::Command ###
+
+All built-in commands are defined as subclasses of `Moonshot::Command`
+in the `Moonshot::Commands` module. Any additional classes that
+subclass this base class will be added as commands. An OptionParser is
+built by calling `#parser` on the subclass, allowing additional
+options for you command. The command name is automatically derived
+from the class name.
+
+For example:
+```ruby
+# moonshot/cli_extensions/my_commands.rb
+class MyCoolCommands < Moonshot::Command
+  self.usage = "my-cool-command MODE"
+  self.description = "Do a really cool thing!"
+
+  def execute(arg)
+    puts "The mode is #{arg}!"
+  end
+end
+```
+
+The Commands have full access to a configured `Moonshot::Controller`,
+via the `#controller` method, just as they did in the previous
+`Moonshot::CLI` subclasses.
+
+## Parameters files removed ##
+
+When Moonshot was first conceived, UsePreviousValue was not a
+supported feature of the UpdateStack API. This meant that if you used
+NoEcho to secure sensitive parameters, there was no way to update a
+stack without having all of the original parameters. This is what lead
+to the decision to support files in the `cloud_formation/parameters`
+directory for each stack. Since then, CloudFormation's APIs have
+improved a great deal, and now with the introduction of
+UsePreviousValue and ChangeSets it's far more reasonable to use AWS as
+the source of truth for the configuration of a Stack.
+
+As such, we no longer require caching all parameters in a file and
+committing it to source control. Instead, we support an "answer file"
+for automating the arguments to stack creation and update. This file
+is passed to `create` or `update` with the `--answer-file` option and
+has the same format as the previous parameters file, but there's no
+reason to commit it to source control. Multiple developers can make
+changes to production environments with confidence knowning that only
+the changes they want to make are the changes that will be made.
+
+## AWS_CREDENTIAL_FILE support removed ##
+
+This legacy form of credential management hasn't been supported by the
+Ruby SDK for quite some time, but when we originally wrote Moonshot
+some teams at Acquia were still using this file for credentials. We
+felt that moving away from these legacy formats was important to the
+1.x release, so if you are using AWS_CREDENTIAL_FILE you will need to
+switch to a [supported credentials management strategy][1].
+
+[1]: http://docs.aws.amazon.com/sdk-for-ruby/v1/developer-guide/set-up-creds.html
+
+## And much more! ##
+
+This guide highlights only the changes one should make to get from
+version 0.7.x to 1.0.0, but there are numerious bugfixes and
+improvements not documented here. For more information, see the
+[release notes][1].
+
+[1]: <To be filled out before cutting 1.0.0 tag.>