documentation for building and testing

BUILD.md

@@ -46,6 +46,16 @@ grunt serve
 
 Alchemy will now be running at localhost:9000.  The Alchemy app that is running is based on the inline configuration in `./app/index.html`.  Additionally, there are a number of sample data sets to play with in the `./app/sample_data/` directory.
 
+Testing
+-------
+Alchemy uses Karma to run test in the mocha framework.  There are a few different that tests are run:  
+
+1. You can run Alchemy's test locally with the `grunt test` command
+1. Continuous integrations runs the test on pull requests using the `grunt test:pr`
+1. Commits made to the main [GraphAlchemist/Alchemy](https://github.com/GraphAlchemist/alchemy) directly are tested on sauce labs by travis using the `grunt test:travis` command
+1. You can use sauce labs to test Alchemy locally by providing [sauce labs credentials](https://saucelabs.com/docs/onboarding) `export SAUCE_USERNAME=foo
+export SAUCE_ACCESS_KEY=bar and runnnig `grunt test:dist`
+
 
 Building the Docs
 -----------------

Gruntfile.coffee

@@ -536,6 +536,7 @@ module.exports = (grunt) ->
 
   grunt.registerTask "test", (target) ->
     grunt.task.run ["clean:server", "copy:coffee", "concurrent:test", "autoprefixer"]  if target isnt "watch"
+    if not target then target = "keepalive"
     switch target
       # for debugging tasks locally
       when "keepalive"

RELEASE.md

@@ -0,0 +1,26 @@
+Release the thing:
+==================
+Hey you, you are releasing Alchemy, awesome!  You can release the Alchemy by running:
+```
+grunt --release
+```
+The `release` flag is to prevent an accidental release when running the default `grunt` command.
+
+In order for the release to work, please make sure the following is true:
+* the documentation site is in a subfolder called **site**
+* update the **package.json** file with the release version
+    * the version should be in the format "X.Y.Z", for example "0.5.0", not "v0.5.0", "v0.5", "0.5"
+    * make sure that the version is different than any other version that has been published to npm or the bower registry
+
+The release task aliases to the following grunt tasks:
+    * "test:dist": tests the site with sauce labs using your credentials.  See the [[BUILD.md]] file for more information on exporting sauce lab credentials to your OS ENV.
+    * "build", build Alchemy vendor files and Alchemy.js
+    * "string-replace", apply version to Alchemy.js
+    * "bumpBower", bump bower version
+    * "shell:commitBuild", commit dist files
+    * "release", create tag and version
+    * "archiveDist", create archive of files to zip for upload to github
+    * "concat:s3", squash vendor and alchemy files for cdn.  The css and js files on CDN include all vendor, assuming that is what users who are not managing their own dependencies want.
+    * "concat:s3Version", apply version numbers to files for cdn
+    * "s3:production" publish files to s3 for cdn
+    * "shell:docs", run grunt file that releases docs (see `./site/Gruntfile.coffee`)