Updated README for v0.5.0

README.md

@@ -1,25 +1,160 @@
-# Ember-cli-deploy-s3
+# ember-cli-deploy-s3
 
-This README outlines the details of collaborating on this Ember addon.
+> An ember-cli-deploy plugin to upload files to S3
+
+<hr/>
+**WARNING: This plugin is only compatible with ember-cli-deploy versions >= 0.5.0**
+<hr/>
+
+This plugin uploads one or more files to an Amazon S3 bucket. It could be used to upload the assets (js, css, images etc) or indeed the application's index.html.
+
+## What is an ember-cli-deploy plugin?
+
+A plugin is an addon that can be executed as a part of the ember-cli-deploy pipeline. A plugin will implement one or more of the ember-cli-deploy's pipeline hooks.
+
+For more information on what plugins are and how they work, please refer to the [Plugin Documentation][1].
+
+## Quick Start
+
+To get up and running quickly, do the following:
+
+- Ensure [ember-cli-deploy-build][2] is installed and configured.
+
+- Install this plugin
+
+```bash
+$ ember install ember-cli-deploy-s3
+```
+
+- Place the following configuration into `config/deploy.js`
+
+```javascript
+ENV.s3 {
+  accessKeyId: '<your-aws-access-key>',
+  secretAccessKey: '<your-aws-secret>',
+  bucket: '<your-s3-bucket>',
+  region: '<the-region-your-bucket-is-in>'
+}
+```
+
+- Run the pipeline
+
+```bash
+$ ember deploy
+```
 
 ## Installation
+Run the following command in your terminal:
 
-* `git clone` this repository
-* `npm install`
-* `bower install`
+```bash
+ember install ember-cli-deploy-s3
+```
 
-## Running
+## ember-cli-deploy Hooks Implemented
 
-* `ember server`
-* Visit your app at http://localhost:4200.
+For detailed information on what plugin hooks are and how they work, please refer to the [Plugin Documentation][1].
 
-## Running Tests
+- `configure`
+- `upload`
+
+## Configuration Options
+
+For detailed information on how configuration of plugins works, please refer to the [Plugin Documentation][1].
+
+### accessKeyId (`required`)
+
+The AWS access key for the user that has the ability to upload to the `bucket`.
+
+*Default:* `undefined`
+
+### secretAccessKey (`required`)
+
+The AWS secret for the user that has the ability to upload to the `bucket`.
+
+*Default:* `undefined`
+
+### bucket (`required`)
+
+The AWS bucket that the files will be uploaded to.
+
+*Default:* `undefined`
+
+### region (`required`)
+
+The region the AWS `bucket` is located in.
+
+*Default:* `us-east-1`
+
+### prefix
 
-* `ember test`
-* `ember test --server`
+A directory within the `bucket` that the files should be uploaded in to.
 
-## Building
+*Default:* `''`
+
+### filePattern
+
+Files that match this pattern will be uploaded to S3. The file pattern must be relative to `distDir`.
+
+*Default:* '**/*.{js,css,png,gif,jpg,map,xml,txt,svg,eot,ttf,woff,woff2}'
+
+### distDir
+
+The root directory where the files matching `filePattern` will be searched for. By default, this option will use the `distDir` property of the deployment context, provided by [ember-cli-deploy-build][2].
+
+*Default:* `context.distDir`
+
+### distFiles
+
+The list of built project files. This option should be relative to `distDir` and should include the files that match `filePattern`. By default, this option will use the `distFiles` property of the deployment context, provided by [ember-cli-deploy-build][2].
+
+*Default:* `context.distDir`
+
+### gzippedFiles
+
+The list of files that have been gziped. This option should be relative to `distDir`. By default, this option will use the `gzippedFiles` property of the deployment context, provided by [ember-cli-deploy-gzip][3].
+
+This option will be used to determine which files in `distDir`, that match `filePattern`, require the gzip content encoding when uploading.
+
+*Default:* `context.gzippedFiles`
+
+### manifestPath
+
+The path to a manifest that specifies the list of files that are to be uploaded to S3.
+
+This manifest file will be used to work out which files don't exist on S3 and, therefore, which files should be uploaded. By default, this option will use the `manifestPath` property of the deployment context, provided by [ember-cli-deploy-manifest][4].
+
+*Default:* `context.manifestPath`
+
+### uploadClient
+
+The client used to upload files to S3. This allows the user the ability to use their own client for uploading instead of the one provided by this plugin.
+
+The client specified MUST implement a function called `upload`.
+
+*Default:* the upload client provided by ember-cli-deploy-s3
+
+### s3Client
+
+The underlying S3 library used to upload the files to S3. This allows the user to use the default upload client provided by this plugin but switch out the underlying library that is used to actually send the files.
+
+The client specified MUST implement functions called `getObject` and `putObject`.
+
+*Default:* the default S3 library is `aws-sdk`
+
+## Prerequisites
+
+The following properties are expected to be present on the deployment `context` object:
+
+- `distDir`      (provided by [ember-cli-deploy-build][2])
+- `distFiles`    (provided by [ember-cli-deploy-build][2])
+- `gzippedFiles` (provided by [ember-cli-deploy-gzip][3])
+- `manifestPath` (provided by [ember-cli-deploy-manifest][4])
+
+## Running Tests
 
-* `ember build`
+- `npm test`
 
-For more information on using ember-cli, visit [http://www.ember-cli.com/](http://www.ember-cli.com/).
+[1]: http://ember-cli.github.io/ember-cli-deploy/plugins "Plugin Documentation"
+[2]: https://github.com/zapnito/ember-cli-deploy-build "ember-cli-deploy-build"
+[3]: https://github.com/lukemelia/ember-cli-deploy-gzip "ember-cli-deploy-gzip"
+[4]: https://github.com/lukemelia/ember-cli-deploy-manifest "ember-cli-deploy-manifest"