updated docs

doc/build/build.md

@@ -24,7 +24,6 @@ The build configuration options:
 * `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
-* `cache` - list of directories within the workspace to cache
 
 [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.
 
@@ -46,14 +45,6 @@ image: library/golang:1.4
 image: index.docker.io/library/golang:1.4
 ```
 
-## Caching
-
-The `cache` attribute supports a list of directories to cache within the build directory. Internally Drone will treat these as volume containers that are shared between all builds within the repository built on the same host machine. Unlike the `volumes` option `cache` is available without the repository being marked as trusted by an administrator[2].
-
-[2] If the repository is public and the build is triggered by a pull request then caching will be disabled for that build. For all other builds caching will be available.
-
-For more information on how to use caching within a project view [caching in Drone](caching.md).
-
 ## Skipping builds
 
 Skip a build by including the text `[CI SKIP]` in your commit message.

doc/build/cache.md

@@ -1,57 +1,30 @@
 # Caching
-Drone allows the caching of directories within the workspace. This can be used to improve the performance of the builds. This document discusses how caching is implemented and provides some general advice for lowering the execution time of builds.
 
-Remember that cached volumes are retained between builds and those volumes are accessible through plugins. They are also available through the host's file system. Any information that is sensitive should not be contained within the cache.
+> **Caution:** this feature is still considered experimental
 
-## Caching Implementation
-Drone uses Docker volumes to handle caching. The volumes are mounted within the build container and are available immediately within the container and any plugins running within the environment.
+Drone allows you to cache directories within the build workspace. When a build successfully completes, the named directories are gzipped and stored on the host machine. When a new build starts, the named directories are restored from the gzipped files. This can be used to improve the performance of your builds.
+
+Below is an example `.drone.yml` configured to cache the `.git` and the `node_modules` directory:
 
-Given the following configuration.
 ```yaml
-build:
-  cache:
-    - foo
-    - fizz/buzz
-```
-Two volumes will be created with their paths resembling the following, with the path left of the : being the location on the host and to the right being the directory within the container. If a different path is specified in the [clone](clone.md) plugin then the paths on the right will be relative to the value in `path` rather than the default paths specified below.
-```
-/tmp/drone/cache/${origin}/${org}/${name}/foo:/drone/src/${origin}/${org}/${name}/foo
-/tmp/drone/cache/${origin}/${org}/${name}/fizz/buzz:/drone/src/${origin}/${org}/${name}/fizz/buzz
-```
-If the drone repository used this caching then the volumes would look like.
-```
-/tmp/drone/cache/github.com/drone/drone/foo:/drone/src/github.com/drone/drone/foo
-/tmp/drone/cache/github.com/drone/drone/fizz/buzz:/drone/src/github.com/drone/drone/fizz/buzz
-```
-
-### Sharing the Cache
-Volumes in Docker are local to the host. When using multiple build machines there will be a copy of the cache on each of these machines. If its desireable to share the cached directories among all the build machines then a distributed file system could be mounted to `/tmp/drone/cache`. Setting up a distrubted file system is beyond the scope of this document but can potentially benifit build times and reduce the disk usage from caching.
-
-### Deleting the Cache
-The caching implementation uses the `/tmp/` directory which is typically cleared every boot unless explicitly changed. If the docker host is never rebooted then a cron job could be used to clear the `/tmp/drone/cache/` periodically. The amount of time to wait clear is dependent upon the number of builds being run, the amount of data being cached, and the size of the repositories. Because of this it is recommended to monitor the disk usage and then make a judgement call based on that data.
-
-## Optimization Strategies
-The following sections, arranged alphabetically, contain optimization strategies for various programming languages and version control systems using caching.
-### C/C++
-_Looking for additional input_
-### Dart
-_Looking for additional input_
-### Git
-When git is used as the version control system the .git directory is a good candidate for caching. Since the git plugin handles the checkout process the only thing needed is to add the .git directory to the cache section.
-```yaml
-build:
-  cache:
+cache:
+  mount:
+    - node_modules
     - .git
 ```
-### Golang
-_Looking for additional input_
-### Java
-_Looking for additional input_
-### JavaScript
-_Looking for additional input_
-### PHP
-_Looking for additional input_
-### Python
-_Looking for additional input_
-### Ruby
-_Looking for additional input_
+
+## Branches and Matrix
+
+Drone keeps a separate cache for each Branch and Matrix combination. Let's say, for example, you are using matrix builds to test `node 0.11.x` and `node 0.12.x` and you are caching `node_modules`. Drone will separately cache `node_modules` for each version of node.
+
+## Pull Requests
+
+Pull requests have read-only access to the cache. This means pull requests are not permitted to re-build the cache. This is done for security and stability purposes, to prevent a pull request from corrupting your cache.
+
+## Deleting the Cache
+
+There is currently no mechanism to automatically delete or flush the cache. This must be done manually, on each worker node. The cache is located in `/var/lib/drone/cache/`.
+
+## Distributed Cache
+
+There is considered outside the scope of Drone. You may, for example, use a distributed filesystem such as `ceph` or `gluster` mounted to `/var/lib/drone/cache/` to share the cache across nodes.

doc/build/deploy.md

@@ -28,27 +28,20 @@ deploy:
       branch: feature/*
 ```
 
-Use a more verbose `.drone.yml` syntax to declare multiple `heroku` deployment steps:
+Declare multiple `heroku` deployment steps:
 
 ```yaml
   # deploy master to our production heroku environment
 
-  heroku_prod:
-    image: plugins/heroku
+  heroku:
+    app: app.com
     when:
       branch: master
 
   # deploy to our staging heroku environment
 
-  heroku_staging:
-    image: plugins/heroku
-    when:
-      branch: stage
-
-  # this is the same as above, but uses a short-hand syntax
-  # and infers the `image` name
-
   heroku:
+    app: staging.app.com
     when:
       branch: stage
 ```

doc/build/notify.md

@@ -23,8 +23,6 @@ publish:
       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

doc/build/secrets.md

@@ -1,5 +1,7 @@
 # Secret Variables
 
+> **Caution:** this feature is still considered experimental
+
 Drone allows you to store secret variables in an encrypted `.drone.sec` file in the root of your repository. This is useful when your build requires sensitive information that should not be stored in plaintext in your `.drone.yml` file.
 
 An example `.drone.sec` yaml file, prior to being encryped:

doc/setup/README.md

@@ -1,4 +1,5 @@
 * [Install](#)
+    * [Ubuntu](ubuntu.md)
     * [Docker](install.md)
 * [Setup](#)
     * [Server](server.md)

doc/setup/mysql.md

@@ -1,4 +1,4 @@
-> **NOTE** the mysql driver is disable until driver issue [#257](https://github.com/go-sql-driver/mysql/issues/257) is resolved
+> **Caution** the mysql driver has known timeout issues. See [#257](https://github.com/go-sql-driver/mysql/issues/257).
 
 # MySQL