updated drone docs

doc/build/README.md

@@ -1,10 +1,9 @@
 * [Overview](overview.md)
-* [Environment](env.md)
+* [Environment](environment.md)
 * [Clone](clone.md)
 * [Build](build.md)
-* [Matrix](martrix.md)
+* [Services](services.md)
 * [Publish](publish.md)
 * [Deploy](deploy.md)
 * [Notify](notify.md)
-* [Services](services.md)
-* [Selenium](selenium.md)
+* [Matrix](martrix.md)

doc/build/build.md

@@ -0,0 +1,63 @@
+# Build
+
+Drone uses the `build` section of the `.drone.yml` to describe your Docker build environment and specify your build and test instructions. The following is an example build definition:
+
+```yaml
+build:
+  image: golang
+  environment:
+    - GOBIN=/drone/bin
+  commands:
+    - go get
+    - go build
+    - go test
+```
+
+## Build options
+
+The build configuration options:
+
+* `image` - any valid Docker image name
+* `pull` - if true, will always attempt to pull the latest image
+* `environment` - list of environment variables, declared in `name=value` format
+* `privileged` - if true, runs the container with extended privileges [1]
+* `volumes` - list of bind mounted volumes on the host machine [1]
+* `net` - sets the container [network mode](https://docs.docker.com/articles/networking/#container-networking) [1]
+* `commands` - list of build commands
+
+[1] Some build options are disabled for security reasons, including `volumes`, `privileged` and `net`. To enable these options, a system administrator must white-list your repository as trusted. This can be done via the repository settings screen.
+
+## Build image
+
+The `image` attribute supports any valid Docker image name:
+
+```yaml
+# Docker library image
+image: golang
+
+# Docker library image, with tag
+image: golang:1.4
+
+# Docker image, full name, with tag
+image: library/golang:1.4
+
+# fully qualified Docker image URI, with tag
+image: index.docker.io/library/golang:1.4
+```
+
+## Build environment
+
+The build environment has access to the following environment variables:
+
+* `CI=true`
+* `DRONE=true`
+* `DRONE_REPO` - repository name for the current build
+* `DRONE_BUILD` - build number for the current build
+* `DRONE_BRANCH` - branch name for the current build
+* `DRONE_COMMIT` - git sha for the current build
+* `DRONE_DIR` - working directory for the current build
+
+
+## Skipping builds
+
+Skip a build by including the text `[CI SKIP]` in your commit message.

doc/build/clone.md

@@ -1,25 +1,25 @@
 # Clone
 
-Drone automatically clones your repository and submodules at the start of your build. No configuration is required, however, you can use the `clone` section of the `.drone.yml` to customize this behavior.
+Drone automatically clones your repository and submodules at the start of your build. No configuration is required. You can, however, use the `clone` section of the `.drone.yml` to customize this behavior as needed.
 
 ## Clone Options
 
 The custom clone options are:
 
-* `depth` creates a shallow clone with truncated history
-* `recursive` recursively clones git submodules
-* `path` relative path inside `/drone/src` where the repository is cloned
+* `depth` - creates a shallow clone with truncated history
+* `recursive` - recursively clones git submodules
+* `path` - relative path inside `/drone/src` where the repository is cloned
 
 This is an example yaml configuration:
 
-```
+```yaml
 clone:
   depth: 50
   recursive: true
   path: github.com/drone/drone
 ```
 
-resulting in the following clone command:
+Which results in the following command:
 
 ```
 git clone --depth=50 --recusive=true \
@@ -27,23 +27,23 @@ git clone --depth=50 --recusive=true \
     /drone/src/github.com/drone/drone
 ```
 
-## Authentication
+## Clone Private Repos
 
-Cloning a private repository requires authentication to the remote system. Drone prefers `git+https` and `netrc` files to authenticate, but will fallback to `git+ssh` and deploy keys if not supported.
+Cloning a private repository requires authentication to the remote system. Drone prefers `git+https` and `netrc` to authenticate, but will fallback to `git+ssh` and deploy keys if not supported.
 
-Drone prefers using `netrc` files for authentication because they allow you to clone other private repositories. This is helpful when you have third party dependencies you need to download (via `go get` or `npm install` or others) that are sourced from a private repository.
+Drone prefers `git+ssh` for authentication because it allows you to clone multiple private repositories. This is helpful when you have git submodules or third party dependencies you need to download (via `go get` or `npm install` or others) that are sourced from a private repository.
 
-Drone only injects the `.netrc` file and `ssh` keys into your build environment if your repository is private, or if the remote system is running in private mode. We do this for security reasons to avoid leaking sensitive data.
+Drone only injects the `netrc` and `id_rsa` files into your build environment if your repository is private, or running in private mode. We do this for security reasons to avoid leaking sensitive data.
 
-## Custom Plugin
+## Clone Plugins
 
 You can override the default `git` plugin by specifying an alternative plugin image. An example use case may be integrating with alternate version control systems, such as mercurial:
 
-```yml
+```yaml
 clone:
   image: bradrydzewski/hg
 
-  # below are plubin-specific parameters
+  # below are plugin-specific parameters
   path: override/default/clone/path
   insecure: false
   verbose: true

doc/build/deploy.md

@@ -0,0 +1,85 @@
+# Deploy
+
+Drone uses the `deploy` section of the `.drone.yml` to configure deployment steps. Drone does not have any built-in deployment capabilities. This functionality is outsourced to [plugins](http://addons.drone.io). See the [plugin marketplace](http://addons.drone.io) for a list of official plugins.
+
+An example plugin that deploys to Heroku:
+
+```yaml
+deploy:
+  heroku:
+    app: pied_piper
+    token: f10e2821bbbea5
+```
+
+## Deploy plugins
+
+Deployment plugins are Docker images that attach to your build environment at runtime. They are declared in the `.drone.yml` using the following format:
+
+```
+deploy:
+  [step_name:]
+    [image:]
+    [options]
+```
+
+An example `heroku` plugin configuration:
+
+```yaml
+deploy:
+  heroku:
+    image: plugins/heroku
+    app: pied_piper
+    token: f10e2821bbbea5
+```
+
+The `image` attribute is optional. If the `image` is not specified Drone attempts to use the `step_name` as the `image` name. The below examples both produce identical output:
+
+```yaml
+  # this step specifies an image
+
+  heroku:
+    image: plubins/heroku
+    app: pied_piper
+    token: f10e2821bbbea5
+
+  # and this step infers the image from the step_name
+
+  heroku:
+    app: pied_piper
+    token: f10e2821bbbea5
+```
+
+The `image` attribute is useful when you need to invoke the same plugin multiple times. For example, we may want to deploy to multiple `heroku` environments depending on branch:
+
+```yaml
+  # deploy master to our production heroku environment
+
+  heroku_prod:
+    image: plugins/heroku
+    when:
+      branch: master
+
+  # deploy to our staging heroku environment
+
+  heroku_staging:
+    image: plugins/heroku
+    when:
+      branch: stage
+```
+
+## Deploy conditions
+
+Use the `when` attribute to limit deployments to a specific branch:
+
+```yaml
+deploy:
+  heroku:
+    when:
+      branch: master
+
+  # you can also do simple matching
+
+  google_appengine:
+    when:
+      branch: feature/*
+```

doc/build/env.md

@@ -0,0 +1,36 @@
+# Environment
+
+The build environment is largely defined by the Docker image you specify in the `.drone.yml`. In addition, Drone will inject default environment variable and private variables.
+
+## Environment Variables
+
+The build environment has access to the following environment variables:
+
+* `CI=true`
+* `DRONE=true`
+* `DRONE_REPO` - repository name for the current build
+* `DRONE_BUILD` - build number for the current build
+* `DRONE_BRANCH` - branch name for the current build
+* `DRONE_COMMIT` - git sha for the current build
+* `DRONE_DIR` - working directory for the current build
+
+
+## Private Variables
+
+Drone allows you to store sensitive data external to the `.drone.yml` and inject at runtime. You can declare private variables in the repository settings screen. These variables are injected into the `.drone.yml` at runtime using the `$$` notation.
+
+An example `.drone.yml` expecting the `HEROKU_TOKEN` private variable:
+
+```yaml
+build:
+  image: golang
+  commands:
+    - go get
+    - go build
+    - go test
+
+publish:
+  heroku:
+    app: pied_piper
+    token: $$HEROKU_TOKEN
+```

doc/build/matrix.md

@@ -0,0 +1,83 @@
+# Matrix Builds
+
+Drone uses the `matrix` section of the `.drone.yml` to define the build matrix. Drone executes a build for each permutation in the matrix, allowing you to build and test a single commit against many configurations.
+
+Below is an example `.drone.yml` that tests a single commit against multiple versions of Go and Redis, resulting in a total of 6 different build permutations:
+
+```yaml
+build:
+  image: golang:$$GO_VERSION
+  commands:
+    - go get
+    - go build
+    - go test
+
+compose:
+  redis:
+    image: redis:$$REDIS_VERSION
+
+matrix:
+  GO_VERSION:
+    - 1.4
+    - 1.3
+  REDIS_VERSION:
+    - 2.6
+    - 2.8
+    - 3.0
+```
+
+## Matrix Variables
+
+Matrix variables are injected into the `.drone.yml` file using the `$$` syntax, performing a simple find / replace. Matrix variables are also injected into your build container as environment variables.
+
+This is an example `.drone.yml` file before injecting the matrix parameters:
+
+```yaml
+build:
+  image: golang:$$GO_VERSION
+  commands:
+    - go get
+    - go build
+    - go test
+
+compose:
+  redis:
+    image: redis:$$REDIS_VERSION
+
+    matrix:
+      GO_VERSION:
+        - 1.4
+      REDIS_VERSION:
+        - 3.0
+```
+
+And this is the `.drone.yml` file after injecting the matrix parameters:
+
+```yaml
+build:
+  image: golang:1.4
+  environment:
+    - GO_VERSION=1.4
+    - REDIS_VERSION=3.0
+  commands:
+    - go get
+    - go build
+    - go test
+    compose:
+      redis:
+        image: redis:3.0
+```
+
+## Matrix Deployments
+
+Matrix builds execute the same `.drone.yml` multiple times, but with different parameters. This means that publish and deployment steps are executed multiple times as well, which is typically undesired. To restrict a publish or deployment step to a single permutation you can add the following condition:
+
+```yaml
+deploy:
+  heroku:
+    app: foo
+    when:
+      matrix:
+        GO_VERSION: 1.4
+        REDIS_VERSION: 3.0
+```

doc/build/notify.md

@@ -0,0 +1,36 @@
+# Notify
+
+Drone uses the `notify` section of the `.drone.yml` to configure notification steps. Drone does not have any built-in notification capabilities. This functionality is outsourced to [plugins](http://addons.drone.io). See the [plugin marketplace](http://addons.drone.io) for a list of official plugins.
+
+An example configuration that sends a Slack notification on build completion:
+
+```yaml
+notify:
+  slack:
+    webhook_url: https://hooks.slack.com/services/f10e2821bbb/200352313bc
+    channel: dev
+    username: drone
+```
+
+## Notification conditions
+
+Use the `when` attribute to limit execution to a specific branch:
+
+```yaml
+publish:
+  slack:
+    when:
+      branch: master
+```
+
+> **NOTE** the ability to limit notifications by status (ie success, failure, etc) is not yet implemented
+
+Or limit execution based on the build status. The below example will only send the notification when the build fails:
+
+```yaml
+publish:
+  slack:
+    when:
+      success: false
+      failure: true
+```

doc/build/overview.md

@@ -0,0 +1,41 @@
+# Overview
+
+In order to configure your build, you must include a `.drone.yml` file in the root of your repository. This documentation describes the `.drone.yml` configuration file format.
+
+Example `.drone.yml` file for a Go repository:
+
+```yaml
+build:
+  image: golang
+  commands:
+    - go get
+    - go build
+    - go test
+```
+
+A more comprehensive example with linked service containers, deployment plugins and notification plugins:
+
+```yaml
+build:
+  image: golang
+  commands:
+    - go get
+    - go build
+    - go test
+
+compose:
+  cache:
+    image: redis
+  database:
+    image: mysql
+
+deploy:
+  heroku:
+    app: pied_piper
+    when:
+      branch: master
+
+notify:
+  slack:
+    channel: myteam
+```

doc/build/publish.md

@@ -0,0 +1,33 @@
+# Publish
+
+Drone uses the `publish` section of the `.drone.yml` to configure publish steps. Drone does not have any built-in publish or artifact capabilities. This functionality is outsourced to [plugins](http://addons.drone.io). See the [plugin marketplace](http://addons.drone.io) for a list of official plugins.
+
+An example configuration that builds a Docker image and publishes to the registry:
+
+```yaml
+pubish:
+  docker:
+    username: kevinbacon
+    password: pa55word
+    email: kevin.bacon@mail.com
+    repo: foo/bar
+    tag: latest
+    file: Dockerfile
+```
+
+## Publish conditions
+
+Use the `when` attribute to limit execution to a specific branch:
+
+```yaml
+publish:
+  docker:
+    when:
+      branch: master
+
+  # you can also do simple matching
+
+  bintray:
+    when:
+      branch: feature/*
+```

doc/build/services.md

@@ -0,0 +1,58 @@
+# Services
+
+Drone uses the `compose` section of the `.drone.yml` to specify supporting containers (ie service containers) that should be started and linked to your build container. The `compose` section of the `.drone.yml` is modeled after `docker-compose`:
+
+```
+compose:
+  [container_name:]
+    image: [image_name]
+    [options]
+```
+
+Example configuration that composes a Postgres and Redis container:
+
+```yaml
+compose:
+  cache:
+    image: redis
+  database:
+    image: postgres
+    environment:
+      - POSTGRES_USER=postgres
+      - POSTGRES_PASSWORD=mysecretpassword
+```
+
+## Service linking
+
+Service containers share the same network as the build container (using `--net=<container>`). This means that you can access your service container using `localhost` or `127.0.0.1`.
+
+## Service options
+
+The service container configuration options:
+
+* `image` - any valid Docker image name
+* `pull` - if true, will always attempt to pull the latest image
+* `environment` - list of environment variables, declared in `name=value` format
+* `privileged` - if true, runs the container with extended privileges [1]
+* `volumes` - list of bind mounted volumes on the host machine [1]
+* `net` - sets the container [network mode](https://docs.docker.com/articles/networking/#container-networking) [1]
+
+[1] Some build options are disabled for security reasons, including `volumes`, `privileged` and `net`. To enable these options, a system administrator must white-list your repository as trusted. This can be done via the repository settings screen.
+
+## Service images
+
+The `image` attribute supports any valid Docker image name:
+
+```yaml
+# Docker library image
+image: postgres
+
+# Docker library image, with tag
+image: postgres:9.2
+
+# Docker image, full name, with tag
+image: library/postgres:9.2
+
+# fully qualified Docker image URI, with tag
+image: index.docker.io/library/postgres:9.2
+```