Docs update (#39)

* add CONTRIBUTING document

* add issue annd PR templates

* rework documentation in README, add example setups

README.md

@@ -6,71 +6,143 @@
 
 A Serverless Framework plugin for deployment of static website assests of your Serverless project to AWS S3.
 
-**First**, install:
+## Installation
 
 ```
 npm install --save serverless-finch
 ```
 
-**Second**, update `serverless.yml` by adding the following:
+## Usage
+
+**First,** update your `serverless.yml` by adding the following:
 
 ```yaml
 plugins:
   - serverless-finch
 
 custom:
   client:
-    bucketName: unique-s3-bucketname-for-your-website-files
-    distributionFolder: client/dist # (Optional) The location of your website. This defaults to client/dist
-    indexDocument: index.html # (Optional) The name of your index document inside your distributionFolder. Defaults to index.html
-    errorDocument: error.html # (Optional) The name of your error document inside your distributionFolder. Defaults to error.html
+    bucketName: [unique-s3-bucketname] # (see Configuration Parameters below)
+    # [other configuration parameters] (see Configuration Parameters below)
 ```
 
-* **Warning:** The plugin will overwrite any data you have in the bucket name you set above if it already exists.
-
+**NOTE:** *For full example configurations, please refer to the [examples](examples) folder.*
 
-**Third**, Create a website folder in the root directory of your Serverless project. This is where your distribution-ready website should live. By default the plugin expects the files to live in a folder called `client/dist`. But this is configurable with the `distributionFolder` option (see the example yaml configuration above).
+**Second**, Create a website folder in the root directory of your Serverless project. This is where your distribution-ready website should live. By default the plugin expects the files to live in a folder called `client/dist`. But this is configurable with the `distributionFolder` option (see the [Configuration Parameters](#configuration-parameters) below).
 
-The plugin uploads the entire distributionFolder to S3 and configures the bucket to host the website and make it publicly available.
+The plugin uploads the entire `distributionFolder` to S3 and configures the bucket to host the website and make it publicly available, also setting other options based the [Configuration Parameters](#configuration-parameters) specified in `serverless.yml`.
 
 To test the plugin initially you can copy/run the following commands in the root directory of your Serverless project to get a quick sample website for deployment:
 
-```
+```bash
 mkdir -p client/dist
 touch client/dist/index.html
 touch client/dist/error.html
 echo "Go Serverless" >> client/dist/index.html
 echo "error page" >> client/dist/error.html
 ```
 
-**Fourth**, run the plugin, and visit your new website!
+**Third**, run the plugin, and visit your new website!
 
 ```
 serverless client deploy [--stage $STAGE] [--region $REGION]
 ```
 
 The plugin should output the location of your newly deployed static site to the console.
 
+**WARNING:** The plugin will overwrite any data you have in the bucket name you set above if it already exists.
+
 If later on you want to take down the website you can use:
 
-```
+```bash
 serverless client remove
 ```
 
-## Release Notes
+### Configuration Parameters
+
+**bucketName**
+
+_required_
+
+```yaml
+custom:
+  client:
+    bucketName: [unique-s3-bucketname]
+```
+
+Use this parameter to specify a unique name for the S3 bucket that your files will be uploaded to.
+
+---
+
+**distributionFolder**
+
+_optional_, default: `client/dist`
+
+```yaml
+custom:
+  client:
+    ...
+    distributionFolder: [path/to/files]
+    ...
+```
+
+Use this parameter to specify the path that contains your website files to be uploaded. This path is relative to the path that your `serverless.yaml` configuration files resides in.
+
+---
 
-### v1.4.*
+**indexDocument**
+
+_optional_, default: `index.html`
+
+```yaml
+custom:
+  client:
+    ...
+    indexDocument: [file-name.ext]
+    ...
+```
+
+The name of your index document inside your `distributionFolder`. This is the file that will be served to a client visiting the base URL for your website.
+
+---
+
+**errorDocument**
+
+_optional_, default: `error.html`
+
+```yaml
+custom:
+  client:
+    ...
+    errorDocument: [file-name.ext]
+    ...
+```
+
+The name of your error document inside your `distributionFolder`. This is the file that will be served to a client if their initial request returns an error (e.g. 404). For an SPA, you may want to set this to the same document specified in `indexDocument` so that all requests are redirected to your index document and routing can be handled on the client side by your SPA.
+
+---
+
+### Command-line Parameters
+
+No command-line parameters exist at this time.
+
+## Contributing
+
+For guidelines on contributing to the project, please refer to our [Contributing](docs/CONTRIBUTING.md) page. 
+
+## Release Notes
 
+### v1.4.\*
 - Added the ability to set custom index and error documents. ([Pull 20](https://github.com/fernando-mc/serverless-finch/pull/20) - [evanseeds](https://github.com/evanseeds))
 
-### v1.3.*
+### v1.3.\*
 - Added the ability to set a `distributionFolder` configuration value. This enables you to upload your website files from a custom directory ([Pull 12](https://github.com/fernando-mc/serverless-finch/pull/12) - [pradel](https://github.com/pradel))
 - Updated the URL to the official static website endpoint URL ([Pull 13](https://github.com/fernando-mc/serverless-finch/pull/13) - [amsross](https://github.com/amsross))
 - Added a new AWS region ([Pull 14](https://github.com/fernando-mc/serverless-finch/pull/14) - [daguix](https://github.com/daguix))
 - Fixed an issue with resolving serverless variables ([Pull 18](https://github.com/fernando-mc/serverless-finch/pull/18) - [shentonfreude](https://github.com/shentonfreude))
 
-### v1.2.*
-- Added the `remove` option to tear down what you deploy. ([Pull 10](https://github.com/fernando-mc/serverless-finch/pull/10) thanks to [redroot](https://github.com/redroot)) 
+### v1.2.\*
+- Added the `remove` option to tear down what you deploy. ([Pull 10](https://github.com/fernando-mc/serverless-finch/pull/10) thanks to [redroot](https://github.com/redroot))
 - Fixed automated builds for the project (no functional differences)
 
 ## Maintainers

docs/CONTRIBUTING.md

@@ -0,0 +1,30 @@
+# Contributing
+
+When contributing to this repository, please first open an issue so that the community of contributors to this repository can discuss the suggestion before a change is made.
+
+## Pull Request Process
+
+Once you have finished making your changes:
+
+1. Make sure that your code satisfies the standards laid out in the [testing](#testing) and [coding style](#coding-style) section of this document.
+2. Update README.md with details on any changes to the interface or behavior of the plugin.
+3. Submit your PR, using the PR template provided to describe the details of your changes.
+
+Then,
+
+4. For substantial changes to the plugin, we will try to get at least two community sign-offs and some discussion of the PR before merging.
+   * For non-controversial or minor PRs (e.g. phrasing updates in the documentation, minor refactoring of constants), one approval will be sufficient to move forward.
+5. A contributor with push access to the repo will merge the PR after all tests and fixes have occured.
+6. A new release will be published (if appropriate).
+
+### Testing
+
+At the time of the writing of this document, we are in the process of developing a full testing plan, but it will likely include unit and integration tests run locally and by our CI tool as well as more manual end-to-end tests. Please refer to issues 33-35 for the discussion. This document will be updated as the process becomes more concrete.
+
+### Coding Style
+
+This repository uses [prettier](https://prettier.io/) to enforce a uniform coding style. You may install an editor plugin for prettier, but code will also be auto-formatted via a git hook whenever you commit code.
+
+### Code of Conduct
+
+Please be polite and respectful in all your communication and actions towards others in the serverless-finch community.

docs/ISSUE_TEMPLATE.md

@@ -0,0 +1,32 @@
+This is a:
+
+* [] Feature request or change
+* [] Bug report
+
+---
+
+For bug reports:
+
+### Expected behavior
+
+### Actual behavior
+
+### Steps to reproduce
+
+* **Operating system:**
+* **serverless-finch version:**
+* `serverless.yml` **that produces bug:**
+* **Command that produces bug:**
+* **Other details:**
+
+---
+
+For feature requests or changes:
+
+### Current behavior (if any)
+
+### Proposed behavior
+
+### Proposed implementation deatils (optional)
+
+### Justification

docs/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,11 @@
+### Background
+
+[reference to original issue or other discussion]
+
+### Proposed changes
+
+[list of features added and/or changed]
+
+### Proposed reviewers (optional)
+
+[@ mentions of other contributors]

examples/SPA/client/dist/index.html

@@ -0,0 +1,11 @@
+<html>
+    <head>
+        <title>My SPA</title>
+    </head>
+
+    <body>
+        <h1>My SPA</h1>
+
+        <script src="my-spa-bundle.js"></script>
+    </body>
+</html>

examples/SPA/serverless.yml

@@ -0,0 +1,21 @@
+service: example-SPA-site
+
+frameworkVersion: "=1.26.0"
+
+provider:
+  name: aws
+  runtime: nodejs6.10
+  stage: dev
+  region: us-east-1
+  profile: serverless-admin
+
+plugins:
+  - serverless-finch
+
+custom:
+  client:
+    bucketName: my-spa-bucket
+    distributionFolder: client/dist 
+    indexDocument: index.html
+    errorDocument: index.html
+

examples/bare-bones/client/dist/error.html

@@ -0,0 +1 @@
+ERROR

examples/bare-bones/client/dist/index.html

@@ -0,0 +1 @@
+Go Serverless!

examples/bare-bones/serverless.yml

@@ -0,0 +1,18 @@
+service: example-site
+
+frameworkVersion: "=1.26.0"
+
+provider:
+  name: aws
+  runtime: nodejs6.10
+  stage: dev
+  region: us-east-1
+  profile: serverless-admin
+
+plugins:
+  - serverless-finch
+
+custom:
+  client:
+    bucketName: my-website-bucket
+