documenting the different available mechanisms in detail

docs/mechanisms/artifact-repository.md

@@ -5,12 +5,24 @@ Supported ArtifactRepositories:
 
 ### S3Bucket
 
+The store action will upload the file using the S3 PutObject API call.
+The local environment must be configured with appropriate credentials.
+
 To create a new S3Bucket ArtifactRepository:
 ```ruby
 class MyApplication < Moonshot::CLI
   self.artifact_repository = S3Bucket.new('my-bucket-name')
 end
 ```
 
-The store action will simply upload the file using the S3 PutObject API call.
-The local environment must be configured with appropriate credentials.
+### S3BucketViaGithubReleases
+
+S3 Bucket repository backed by GitHub releases.
+If a SemVer package isn't found in S3, it is downloaded from GitHub releases to avoid not being able to release in case there is trouble with AWS S3.
+
+To create a new S3BucketViaGithubReleases ArtifactRepository:
+```ruby
+class MyApplication < Moonshot::CLI
+  self.artifact_repository = S3BucketViaGithubReleases.new('my-bucket-name')
+end
+```

docs/mechanisms/build.md

@@ -1,6 +1,6 @@
-## BuildMechanism
+# BuildMechanism
 
-### Script
+## Script
 
 The Script BuildMechanism will execute a local shell script, with certain
 expectations. The script will run with some environment variables:
@@ -10,3 +10,55 @@ expectations. The script will run with some environment variables:
 
 If the file is not created by the build script, deployment will fail. Otherwise,
 the output file will be uploaded using the ArtifactRepository.
+
+Sample Usage
+```ruby
+#!/usr/bin/env ruby
+
+require 'moonshot'
+
+# Set up Moonshot tooling for our environment.
+class MoonshotSampleApp < Moonshot::CLI
+  self.build_mechanism = Script.new('bin/build.sh')
+...
+```
+
+## Github Release
+
+A build mechanism that creates a tag and GitHub release. Could be used to delegate other building steps after GitHub release is created.
+
+Sample Usage
+
+```ruby
+#!/usr/bin/env ruby
+
+require 'moonshot'
+
+# Set up Moonshot tooling for our environment.
+class MoonshotSampleApp < Moonshot::CLI
+	wait_for_travis_mechanism = TravisDeploy.new("acquia/moonshot", true)
+  self.build_mechanism = GithubRelease.new(wait_for_travis_mechanism)
+...
+```
+
+## Travis Deploy
+
+The Travis Build Mechanism waits for Travis-CI to finish building a job matching the VERSION (see above) and the output of the travis job has to be 'BUILD=1'. Can be used to make sure that the travis job for the repository for that version actually finished before the deployment step can be executed.
+
+Sample Usage
+```ruby
+#!/usr/bin/env ruby
+
+require 'moonshot'
+
+# Set up Moonshot tooling for our environment.
+class MoonshotSampleApp < Moonshot::CLI
+  # First argument is the repository as known by travis.
+  # Second argument is wether or not you are using travis pro.
+  self.build_mechanism = TravisDeploy.new("acquia/moonshot", pro: true)
+...
+```
+
+## Version Proxy
+
+@Todo Document and clarify the use-case of the Version Proxy.

docs/mechanisms/deployment.md

@@ -1,24 +1,41 @@
+# DeploymentMechanism
 
-## DeploymentMechanism
+## CodeDeploy
 
-Supported DeploymentMechanisms:
-- CodeDeploy
-
-### CodeDeploy
-
-The CodeDeploy DeploymentMechanism will create a CodeDeploy Application and
-Deployment Group matching the application name. The created Deployment Group
-will point at the logical resource id provided to the constructor (e.g.
-`CodeDeploy.new(asg: 'MyAutoScalingGroup')`). During the `deploy-code` action,
-the ArtifactRepository is checked for compatibility with CodeDeploy. Currently
-only the S3Bucket is supported, though CodeDeploy itself supports deploying from
-a git source.
+The CodeDeploy DeploymentMechanism will create a CodeDeploy Application and Deployment Group matching the application name. The created Deployment Group will point at the logical resource id provided to the constructor (e.g. `CodeDeploy.new(asg: 'MyAutoScalingGroup')`). During the `deploy-code` action, the ArtifactRepository is checked for compatibility with CodeDeploy. Currently only the S3Bucket is supported, though CodeDeploy itself supports deploying from a git source.
 
 Assumptions made by the CodeDeploy mechanism:
+
 - You are using an S3Bucket ArtifactRepository.
 - You want to deploy using the OneAtATime method.
 - Your build artifact contains an appspec.yml file.
 
+Sample Usage
+```ruby
+#!/usr/bin/env ruby
+
+require 'moonshot'
+
+# Set up Moonshot tooling for our environment.
+class MoonshotSampleApp < Moonshot::CLI
+  self.deployment_mechanism = CodeDeploy.new(asg: 'AutoScalingGroup', role: 'CodeDeployRole', app_name: 'my_app_name')
+...
+```
+Parameters
+
+### asg | string
+
+The logical name of the AutoScalingGroup to create and manage a Deployment
+Group for in CodeDeploy.
+
+### role | string
+
+IAM role with AWSCodeDeployRole policy. CodeDeployRole is considered as default role if its not specified.
+
+### app_name | string,nil
+
+The name of the CodeDeploy Application and Deployment Group. By default, this is the same as the stack name, and probably what you want. If you have multiple deployments in a single Stack, they must have unique names.
+
 For more information about CodeDeploy, see the [AWS Documentation][1].
 
 [1]: http://docs.aws.amazon.com/codedeploy/latest/userguide/welcome.html

docs/user-guide/parent_stacks.md

@@ -1,4 +1,4 @@
-## Parent Stacks
+# Parent Stacks
 
 Moonshot supports referencing another CloudFormation stack as a
 "Parent" during creation time. This relationship is used only for creation,
@@ -7,11 +7,12 @@ stack will be used as parameters, and saved into a local .yml file for future
 use.
 
 The order of precedence for parameters is:
+
 - Existing parameter overrides in the .yml file.
 - The value from the parent stack's output.
 - Any default value in the CloudFormation template.
 
-### A word of caution
+## A word of caution
 
 It's not advisable to use default values in the CloudFormation template.
 Consider the following example:

lib/moonshot/build_mechanism/github_release.rb

@@ -71,7 +71,7 @@ def confirm_or_fail(version)
       say("Changelog for #{version}", :yellow)
       say("#{@changes}\n\n")
 
-      q = "Do you wan't to tag and release this commit as #{version}? [y/n]"
+      q = "Do you want to tag and release this commit as #{version}? [y/n]"
       raise Thor::Error, 'Release declined.' unless yes?(q)
     end