Update Compose docs to reflect changes in 1.18 release

Signed-off-by: Joffrey F <joffrey@docker.com>

compose/compose-file/compose-file-v2.md

@@ -195,6 +195,19 @@ at build time is the value in the environment where Compose is running.
 > **Note**: YAML boolean values (`true`, `false`, `yes`, `no`, `on`, `off`) must
 > be enclosed in quotes, so that the parser interprets them as strings.
 
+#### extra_hosts
+
+Add hostname mappings at build-time. Use the same values as the docker client `--add-host` parameter.
+
+    extra_hosts:
+     - "somehost:162.242.195.82"
+     - "otherhost:50.31.209.229"
+
+An entry with the ip address and hostname will be created in `/etc/hosts` inside containers for this build, e.g:
+
+    162.242.195.82  somehost
+    50.31.209.229   otherhost
+
 #### labels
 
 > Added in [version 2.1](compose-versioning.md#version-21) file format
@@ -948,6 +961,7 @@ port (a random host port will be chosen).
      - "127.0.0.1:8001:8001"
      - "127.0.0.1:5000-5010:5000-5010"
      - "6060:6060/udp"
+     - "12400-12500:1240"
 
 ### scale
 
@@ -1038,17 +1052,22 @@ Disables the user namespace for this service, if Docker daemon is configured wit
 See [dockerd](/engine/reference/commandline/dockerd.md#disable-user-namespace-for-a-container) for
 more information.
 
-### volumes, volume\_driver
+### volumes
 
-Mount paths or named volumes, optionally specifying a path on the host machine
+Mount host folders or named volumes. Named volumes need to be specified with the
-(`HOST:CONTAINER`), or an access mode (`HOST:CONTAINER:ro`).
-For [version 2 files](compose-versioning.md#version-2), named volumes need to be specified with the
 [top-level `volumes` key](#volume-configuration-reference).
 
 You can mount a relative path on the host, which will expand relative to
 the directory of the Compose configuration file being used. Relative paths
 should always begin with `.` or `..`.
 
+#### Short syntax
+
+The short syntax uses the generic `[SOURCE:]TARGET[:MODE]` format, where
+`SOURCE` can be either a host path or volume name. `TARGET` is the container
+path where the volume will be mounted. Standard modes are `ro` for read-only
+and `rw` for read-write (default).
+
     volumes:
       # Just specify a path and let the Engine create a volume
       - /var/lib/mysql
@@ -1065,26 +1084,69 @@ should always begin with `.` or `..`.
       # Named volume
       - datavolume:/var/lib/mysql
 
-If you do not use a host path, you may specify a `volume_driver`.
+#### Long syntax
+
+> [Added in version 2.3 file format](compose-versioning.md#version-23).
+
+The long form syntax allows the configuration of additional fields that can't be
+expressed in the short form.
+
+- `type`: the mount type `volume`, `bind`, `tmpfs` or `npipe`
+- `source`: the source of the mount, a path on the host for a bind mount, or the
+  name of a volume defined in the
+  [top-level `volumes` key](#volume-configuration-reference). Not applicable for a tmpfs mount.
+- `target`: the path in the container where the volume will be mounted
+- `read_only`: flag to set the volume as read-only
+- `bind`: configure additional bind options
+  - `propagation`: the propagation mode used for the bind
+- `volume`: configure additional volume options
+  - `nocopy`: flag to disable copying of data from a container when a volume is
+    created
+
+
+```none
+version: "3.2"
+services:
+  web:
+    image: nginx:alpine
+    ports:
+      - "80:80"
+    volumes:
+      - type: volume
+        source: mydata
+        target: /data
+        volume:
+          nocopy: true
+      - type: bind
+        source: ./static
+        target: /opt/app/static
+
+networks:
+  webnet:
+
+volumes:
+  mydata:
+```
+
+> **Note:** When creating bind mounts, using the long syntax requires the
+> referenced folder to be created beforehand. Using the short syntax will
+> create the folder on the fly if it doesn't exist.
+> See the [bind mounts documentation](/engine/admin/volumes/bind-mounts.md/#differences-between--v-and---mount-behavior)
+> for more information.
+
+### volume\_driver
+
+Specify a default volume driver to be used for all declared volumes on this
+service.
 
     volume_driver: mydriver
 
-There are several things to note, depending on which
+> **Note:** In [version 2 files](compose-versioning.md#version-2), this
-[Compose file version](#versioning) you're using:
+> option will only apply to anonymous volumes (those specified in the image,
+> or specified under `volumes` without an explicit named volume or host path).
+> To configure the driver for a named volume, use the `driver` key under the
+> entry in the [top-level `volumes` option](#volume-configuration-reference).
 
--   You can use `volume_driver` in [version 2 files](compose-versioning.md#version-2),
-    but it will only apply to anonymous volumes (those specified in the image,
-    or specified under `volumes` without an explicit named volume or host path).
-    To configure the driver for a named volume, use the `driver` key under the
-    entry in the
-    [top-level `volumes` option](#volume-configuration-reference).
-
--   For [version 1 files](compose-versioning.md#version-1), both named volumes and
-    container volumes use the specified driver. This changes in version 2 per the above reference to anonymous volumes.
-
--   No path expansion will be done if you have also specified a `volume_driver`.
-    For example, if you specify a mapping of `./foo:/data`, the `./foo` part
-    will be passed straight to the volume driver without being expanded.
 
 See [Docker Volumes](/engine/userguide/dockervolumes.md) and
 [Volume Plugins](/engine/extend/plugins_volume.md) for more information.
@@ -1124,13 +1186,15 @@ then read-write will be used.
 
 {: id="cpu-and-other-resources"}
 
-### cpu_count, cpu_percent, cpu\_shares, cpu\_quota, cpus, cpuset, domainname, hostname, ipc, mac\_address, mem\_limit, memswap\_limit, mem\_swappiness, mem\_reservation, oom_score_adj, privileged, read\_only, shm\_size, stdin\_open, tty, user, working\_dir
+### cpu_count, cpu_percent, cpu\_shares, cpu\_quota, cpus, cpuset, domainname, hostname, ipc, mac\_address, mem\_limit, memswap\_limit, mem\_swappiness, mem\_reservation, oom_kill_disable, oom_score_adj, privileged, read\_only, shm\_size, stdin\_open, tty, user, working\_dir
 
 Each of these is a single value, analogous to its
 [docker run](/engine/reference/run.md) counterpart.
 
 > **Note:** The following options were added in [version 2.2](compose-versioning.md#version-22):
 > `cpu_count`, `cpu_percent`, `cpus`.
+> The following options were added in [version 2.1](compose-versioning.md#version-21):
+> `oom_kill_disable`
 
     cpu_count: 2
     cpu_percent: 50
@@ -1153,6 +1217,7 @@ Each of these is a single value, analogous to its
     privileged: true
 
     oom_score_adj: 500
+    oom_kill_disable: true
 
     read_only: true
     shm_size: 64M
@@ -1449,11 +1514,29 @@ refer to it within the Compose file:
         external:
           name: actual-name-of-network
 
-#### host or none
 
-Not supposed for version 2 `docker-compose` files. Use
+Not supported for version 2 `docker-compose` files. Use
 [network_mode](#network_mode) instead.
 
+### name
+
+> [Added in version 2.1 file format](compose-versioning.md#version-21)
+
+Set a custom name for this network.
+
+    version: '2.1'
+    networks:
+      network1:
+        name: my-app-net
+
+It can also be used in conjuction with the `external` property:
+
+    version: '2.1'
+    networks:
+      network1:
+        external: true
+        name: my-app-net
+
 ## Variable substitution
 
 {% include content/compose-var-sub.md %}

compose/compose-file/index.md

@@ -314,6 +314,23 @@ those used by other software.
         - "com.example.department=Finance"
         - "com.example.label-with-empty-value"
 
+#### shm_size
+
+> Added in [version 3.5](compose-versioning.md#version-35) file format
+
+Set the size of the `/dev/shm` partition for this build's containers. Specify
+as an integer value representing the number of bytes or as a string expressing
+a [byte value](#specifying-byte-values).
+
+    build:
+      context: .
+      shm_size: '2gb'
+
+
+    build:
+      context: .
+      shm_size: 10000000
+
 ### cap_add, cap_drop
 
 Add or drop container capabilities.
@@ -1785,6 +1802,22 @@ format that looks like this:
 The supported units are `us`, `ms`, `s`, `m` and `h`.
 
 
+## Specifying byte values
+
+Some configuration options, such as the `shm_size` sub-option for
+[`build`](#build), accept a byte value as a string in a format
+that looks like this:
+
+    2b
+    1024kb
+    2048k
+    300m
+    1gb
+
+The supported units are `b`, `k`, `m` and `g`, and their alternative notation `kb`,
+`mb` and `gb`. Please note that decimal values are not supported at this time.
+
+
 ## Volume configuration reference
 
 While it is possible to declare [volumes](#volumes) on the file as part of the
@@ -1902,6 +1935,25 @@ conflicting with those used by other software.
       - "com.example.department=IT/Ops"
       - "com.example.label-with-empty-value"
 
+### name
+
+> [Added in version 3.4 file format](compose-versioning.md#version-34)
+
+Set a custom name for this volume.
+
+    version: '3.4'
+    volumes:
+      data:
+        name: my-app-data
+
+It can also be used in conjuction with the `external` property:
+
+    version: '3.4'
+    volumes:
+      data:
+        external: true
+        name: my-app-data
+
 ## Network configuration reference
 
 The top-level `networks` key lets you specify networks to be created.
@@ -2105,6 +2157,25 @@ refer to it within the Compose file:
         external:
           name: actual-name-of-network
 
+### name
+
+> [Added in version 3.5 file format](compose-versioning.md#version-35)
+
+Set a custom name for this network.
+
+    version: '3.5'
+    networks:
+      network1:
+        name: my-app-net
+
+It can also be used in conjuction with the `external` property:
+
+    version: '3.5'
+    networks:
+      network1:
+        external: true
+        name: my-app-net
+
 ## configs configuration reference
 
 The top-level `configs` declaration defines or references
@@ -2116,6 +2187,8 @@ stack. The source of the config is either `file` or `external`.
 - `external`: If set to true, specifies that this config has already been
   created. Docker will not attempt to create it, and if it does not exist, a
   `config not found` error occurs.
+- `name`: The actual name of the config object in Docker. Introduced with the
+  3.5 file format.
 
 In this example, `my_first_config` will be created (as
 `<stack_name>_my_first_config)`when the stack is deployed,
@@ -2159,6 +2232,8 @@ stack. The source of the secret is either `file` or `external`.
 - `external`: If set to true, specifies that this secret has already been
   created. Docker will not attempt to create it, and if it does not exist, a
   `secret not found` error occurs.
+- `name`: The actual name of the config object in Docker. Introduced with the
+  3.5 file format.
 
 In this example, `my_first_secret` will be created (as
 `<stack_name>_my_first_secret)`when the stack is deployed,

compose/reference/build.md

@@ -13,6 +13,7 @@ Options:
     --force-rm              Always remove intermediate containers.
     --no-cache              Do not use cache when building the image.
     --pull                  Always attempt to pull a newer version of the image.
+    -m, --memory MEM        Sets memory limit for the bulid container.
     --build-arg key=val     Set build-time variables for one service.
 ```
 

compose/reference/down.md

@@ -9,15 +9,17 @@ notoc: true
 Usage: down [options]
 
 Options:
-    --rmi type          Remove images. Type must be one of:
+    --rmi type              Remove images. Type must be one of:
-                        'all': Remove all images used by any service.
+                              'all': Remove all images used by any service.
-                        'local': Remove only images that don't have a custom tag
+                              'local': Remove only images that don't have a
-                        set by the `image` field.
+                              custom tag set by the `image` field.
-    -v, --volumes       Remove named volumes declared in the `volumes` section
+    -v, --volumes           Remove named volumes declared in the `volumes`
-                        of the Compose file and anonymous volumes
+                            section of the Compose file and anonymous volumes
-                        attached to containers.
+                            attached to containers.
-    --remove-orphans    Remove containers for services not defined in the
+    --remove-orphans        Remove containers for services not defined in the
-                        Compose file
+                            Compose file
+    -t, --timeout TIMEOUT   Specify a shutdown timeout in seconds.
+                            (default: 10)
 ```
 
 Stops containers and removes containers, networks, volumes, and images

compose/reference/run.md

@@ -6,7 +6,9 @@ notoc: true
 ---
 
 ```
-Usage: run [options] [-v VOLUME...] [-p PORT...] [-e KEY=VAL...] SERVICE [COMMAND] [ARGS...]
+Usage:
+    run [options] [-v VOLUME...] [-p PORT...] [-e KEY=VAL...] [-l KEY=VALUE...]
+        SERVICE [COMMAND] [ARGS...]
 
 Options:
     -d                    Detached mode: Run container in the background, print
@@ -14,6 +16,7 @@ Options:
     --name NAME           Assign a name to the container
     --entrypoint CMD      Override the entrypoint of the image.
     -e KEY=VAL            Set an environment variable (can be used multiple times)
+    -l, --label KEY=VAL   Add or override a label (can be used multiple times)
     -u, --user=""         Run as specified username or uid
     --no-deps             Don't start linked services.
     --rm                  Remove container after run. Ignored in detached mode.

release-notes/docker-compose.md

@@ -5,6 +5,81 @@ keywords: release notes, compose
 toc_max: 2
 ---
 
+## 1.18.0 (2017-12-15)
+
+### New features
+
+#### Compose file version 3.5
+
+- Introduced version 3.5 of the `docker-compose.yml` specification.
+  This version requires to be used with Docker Engine 17.06.0 or above
+
+- Added support for the `shm_size` parameter in build configurations
+
+- Added support for the `isolation` parameter in service definitions
+
+- Added support for custom names for network, secret and config definitions
+
+#### Compose file version 2.3
+
+- Added support for `extra_hosts` in build configuration
+
+- Added support for the [long syntax](/compose/compose-file.md#long-syntax-3) for volume entries, as previously
+  introduced in the 3.2 format. Note that using this syntax will create
+  [mounts](/engine/admin/volumes/bind-mounts.md) instead of volumes.
+
+#### Compose file version 2.1 and up
+
+- Added support for the `oom_kill_disable` parameter in service definitions
+  (2.x only)
+
+- Added support for custom names for network definitions (2.x only)
+
+
+#### All formats
+
+- Values interpolated from the environment will now be converted to the
+  proper type when used in non-string fields.
+
+- Added support for `--label` in `docker-compose run`
+
+- Added support for `--timeout` in `docker-compose down`
+
+- Added support for `--memory` in `docker-compose build`
+
+- Setting `stop_grace_period` in service definitions now also sets the
+  container's `stop_timeout`
+
+### Bugfixes
+
+- Fixed an issue where Compose was still handling service hostname according
+  to legacy engine behavior, causing hostnames containing dots to be cut up
+
+- Fixed a bug where the `X-Y:Z` syntax for ports was considered invalid
+  by Compose
+
+- Fixed an issue with CLI logging causing duplicate messages and inelegant
+  output to occur
+
+- Fixed a bug where the valid `${VAR:-}` syntax would cause Compose to
+  error out
+
+- Fixed a bug where `env_file` entries using an UTF-8 BOM were being read
+  incorrectly
+
+- Fixed a bug where missing secret files would generate an empty directory
+  in their place
+
+- Added validation for the `test` field in healthchecks
+
+- Added validation for the `subnet` field in IPAM configurations
+
+- Added validation for `volumes` properties when using the long syntax in
+  service definitions
+
+- The CLI now explicit prevents using `-d` and `--timeout` together
+  in `docker-compose up`
+
 ## 1.17.0 (2017-11-03)
 
 ### New features