add initial specification document

SPECIFICATION.md

@@ -0,0 +1,196 @@
+Specification
+=============
+
+## env
+
+*type*: object
+
+*value*: key/value pairs of environment driver/options
+
+```yaml
+env:
+  docker: php:latest
+  vagrant:
+    - debian
+    - ubuntu
+```
+
+```json
+{
+  "env": {
+    "docker": "php:latest",
+    "vagrant": [
+      "debian",
+      "ubuntu"
+    ]
+  }
+}
+```
+
+```ini
+[env]
+docker = php:latest
+vagrant =
+    debian
+    ubuntu
+```
+
+## before_build
+
+*type*: list/string
+
+*value*: single line string command to run or list of commands to be run before the _build_ step
+
+```yaml
+before_build:
+  - sudo apt-get update
+  - sudo apt-get install <package>
+---
+before_build: <run command here>
+```
+
+```json
+{
+  "before_build": [
+    "sudo apt-get update",
+    "sudo apt-get install <package>"
+  ]
+}
+{
+  "before_build": "<run command here>"
+}
+```
+
+```ini
+[global]
+before_build =
+    sudo apt-get update
+    sudo apt-get install <package>
+before_build = <run command here>
+```
+
+## build
+
+*type*: list/string
+
+*value*: single line string command to run or list of commands to be run as the main build script
+
+```yaml
+build:
+  - <run command here>
+---
+build: <run command here>
+```
+
+```json
+{
+  "build": [
+    "<run command here>"
+  ]
+}
+{
+  "build": "<run command here>"
+}
+```
+
+```ini
+[global]
+build =
+    <run command here>
+build = <run command here>
+```
+
+## after_build
+
+*type*: string/list
+
+*value*: after build is either a single command string or a list of commands to run after the _build_, this is always run
+regardless of success/failure of the build, and is run before the success and failure version
+```yaml
+after_build: <run command here>
+---
+after_build:
+  - <run command here>
+```
+
+```json
+{
+  "after_build": "<run command here>"
+}
+{
+  "after_build": [
+    "<run command here>"
+  ]
+}
+```
+
+```ini
+[global]
+after_build = <run command here>
+after_build =
+    <run command here>
+```
+
+## after_success
+
+*type*: string/list
+
+*value*: after success is either a single command string or a list of commands to run after the _build_,
+only if the _build_ step was succesful
+
+```yaml
+after_success: <run command here>
+---
+after_success:
+  - <run command here>
+```
+
+```json
+{
+  "after_success": "<run command here>"
+}
+{
+  "after_success": [
+    "<run command here>"
+  ]
+}
+```
+
+```ini
+[global]
+after_success = <run command here>
+after_success =
+    <run command here>
+```
+
+## after_failure
+
+*type*: string/list
+
+*value*: after failure is either a single command string or a list of commands to run after the _build_,
+only if the _build_ step failed
+
+```yaml
+after_failure: <run command here>
+---
+after_failure:
+  - <run command here>
+```
+
+```json
+{
+  "after_failure": "<run command here>"
+}
+{
+  "after_failure": [
+    "<run command here>"
+  ]
+}
+```
+
+```ini
+[global]
+after_failure = <run command here>
+after_failure =
+    <run command here>
+```