From b253efd8a77447c7ad4f6a6aa5101510704782b1 Mon Sep 17 00:00:00 2001
From: Joffrey F <joffrey@docker.com>
Date: Wed, 18 Nov 2015 17:45:10 -0800
Subject: [PATCH] Update docs to define and document new compose.yml file
 format

Add volume configuration reference section.

Signed-off-by: Joffrey F <joffrey@docker.com>
---
 docs/compose-file.md | 86 ++++++++++++++++++++++++++++++++++++++++++++
 docs/index.md        | 26 ++++++++------
 2 files changed, 102 insertions(+), 10 deletions(-)

diff --git a/docs/compose-file.md b/docs/compose-file.md
index 2a6028b8..29e0c647 100644
--- a/docs/compose-file.md
+++ b/docs/compose-file.md
@@ -24,6 +24,64 @@ As with `docker run`, options specified in the Dockerfile (e.g., `CMD`,
 `EXPOSE`, `VOLUME`, `ENV`) are respected by default - you don't need to
 specify them again in `docker-compose.yml`.
 
+## Versioning
+
+It is possible to use different versions of the `compose.yml` format.
+Below are the formats currently supported by compose.
+
+
+### Version 1
+
+Compose files that do not declare a version are considered "version 1". In
+those files, all the [services](#service-configuration-reference) are declared
+at the root of the document.
+
+Version 1 files do not support the declaration of
+named [volumes](#volume-configuration-reference)
+
+Example:
+
+    web:
+      build: .
+      ports:
+       - "5000:5000"
+      volumes:
+       - .:/code
+       - logvolume01:/var/log
+      links:
+       - redis
+    redis:
+      image: redis
+
+
+### Version 2
+
+Compose files using the version 2 syntax must indicate the version number at
+the root of the document. All [services](#service-configuration-reference)
+must be declared under the `services` key.
+Named [volumes](#volume-configuration-reference) must be declared under the
+`volumes` key.
+
+Example:
+
+    version: 2
+    services:
+      web:
+        build: .
+        ports:
+         - "5000:5000"
+        volumes:
+         - .:/code
+         - logvolume01:/var/log
+        links:
+         - redis
+      redis:
+        image: redis
+    volumes:
+      logvolume01:
+        driver: default
+
+
 ## Service configuration reference
 
 This section contains a list of all configuration options supported by a service
@@ -413,6 +471,34 @@ Each of these is a single value, analogous to its
     stdin_open: true
     tty: true
 
+
+## Volume configuration reference
+
+While it is possible to declare volumes on the fly as part of the service
+declaration, this section allows you to create named volumes that can be
+reused across multiple services (without relying on `volumes_from`), and are
+easily retrieved and inspected using the docker command line or API.
+See the [docker volume](http://docs.docker.com/reference/commandline/volume/)
+subcommand documentation for more information.
+
+### driver
+
+Specify which volume driver should be used for this volume. Defaults to
+`local`. An exception will be raised if the driver is not available.
+
+      driver: foobar
+
+### driver_opts
+
+Specify a list of options as key-value pairs to pass to the driver for this
+volume. Those options are driver dependent - consult the driver's
+documentation for more information. Optional.
+
+      driver_opts:
+        foo: "bar"
+        baz: 1
+
+
 ## Variable substitution
 
 Your configuration options can contain environment variables. Compose uses the
diff --git a/docs/index.md b/docs/index.md
index 36b93a39..6e8f2090 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -31,16 +31,22 @@ they can be run together in an isolated environment.
 
 A `docker-compose.yml` looks like this:
 
-    web:
-      build: .
-      ports:
-       - "5000:5000"
-      volumes:
-       - .:/code
-      links:
-       - redis
-    redis:
-      image: redis
+    version: 2
+    services:
+      web:
+        build: .
+        ports:
+         - "5000:5000"
+        volumes:
+         - .:/code
+         - logvolume01:/var/log
+        links:
+         - redis
+      redis:
+        image: redis
+    volumes:
+      logvolume01:
+        driver: default
 
 For more information about the Compose file, see the
 [Compose file reference](compose-file.md)