Document new features in Compose 1.17 (#5019) (#5021)

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

_config.yml

@@ -20,7 +20,7 @@ docker_ce_stable_version: "17.09"
 latest_stable_docker_engine_api_version: "1.32"
 docker_ce_edge_version: "17.10"
 docker_ee_version: "17.06"
-compose_version: "1.16.1"
+compose_version: "1.17.0"
 machine_version: "0.13.0"
 distribution_version: "2.6"
 

_includes/content/compose-extfields-sub.md

@@ -0,0 +1,63 @@
+It is possible to re-use configuration fragments using extension fields. Those
+special fields can be of any format as long as they are located at the root of
+your Compose file and their name start with the `x-` character sequence.
+
+    version: '2.1'
+    x-custom:
+      items:
+        - a
+        - b
+      options:
+        max-size: '12m'
+      name: "custom"
+
+The contents of those fields will be ignored by Compose, but they can be
+inserted in your resource definitions using [YAML anchors](http://www.yaml.org/spec/1.2/spec.html#id2765878).
+For example, if you want several of your services to use the same logging
+configuration:
+
+    logging:
+      options:
+        max-size: '12m'
+        max-file: 5
+      driver: json-file
+
+You may write your Compose file as follows:
+
+version: '2.1'
+x-logging:
+  &default-logging
+  options:
+    max-size: '12m'
+    max-file: 5
+  driver: json-file
+
+services:
+  web:
+    image: myapp/web:latest
+    logging: *default-logging
+  db:
+    image: mysql:latest
+    logging: *default-logging
+
+It is also possible to partially override values in extension fields using
+the [YAML merge type](http://yaml.org/type/merge.html). For example:
+
+    version: '2.1'
+    x-volumes:
+      &default-volume
+      driver: foobar-storage
+
+    services:
+      web:
+        image: myapp/web:latest
+        volumes: ["vol1", "vol2", "vol3"]
+    volumes:
+      vol1: *default-volume
+      vol2:
+        << : *default-volume
+        name: volume02
+      vol3:
+        << : *default-volume
+        driver: default
+        name: volume-local

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

@@ -236,6 +236,23 @@ build.
       context: .
       network: custom_network_1
 
+#### shm_size
+
+> Added in [version 2.3](compose-versioning.md#version-23) 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
+
 #### target
 
 > Added in [version 2.3](compose-versioning.md#version-23) file format
@@ -1441,6 +1458,12 @@ Not supposed for version 2 `docker-compose` files. Use
 
 {% include content/compose-var-sub.md %}
 
+## Extension fields
+
+> [Added in version 2.1 file format](compose-versioning.md#version-21).
+
+{% include content/compose-extfields-sub.md %}
+
 ## Compose documentation
 
 - [User guide](/compose/index.md)

compose/compose-file/compose-versioning.md

@@ -223,7 +223,8 @@ supported by **Compose 1.16.0+**.
 
 Introduces the following additional parameters:
 
-- [`target`](compose-file-v2.md#target) for [build configurations](compose-file-v2.md#build)
+- [`target`](compose-file-v2.md#target) and [`shm_size`](compose-file-v2.md#shm_size)
+  for [build configurations](compose-file-v2.md#build)
 - `start_period` for [`healthchecks`](compose-file-v2.md#healthcheck)
 
 ### Version 3
@@ -251,6 +252,18 @@ Introduces the following additional parameters:
 - [`configs`](/compose/compose-file/index.md#configs)
 - [deploy `endpoint_mode`](/compose/compose-file/index.md#endpointmode)
 
+### Version 3.4
+
+An upgrade of [version 3](#version-3) that introduces new parameters. It is
+only available with Docker Engine version **17.09.0** and higher.
+
+Introduces the following additional parameters:
+
+- `target` and `network` in [build configurations](index.md#build)
+- `start_period` for [`healthchecks`](index.md#healthcheck)
+- `order` for [update configurations](index.md#update_config)
+- `name` for [volumes](index.md#volume-configuration-reference)
+
 ## Upgrading
 
 ### Version 2.x to 3.x

compose/compose-file/index.md

@@ -2189,6 +2189,12 @@ stack.
 
 {% include content/compose-var-sub.md %}
 
+## Extension fields
+
+> [Added in version 3.4 file format](compose-versioning.md#version-34).
+
+{% include content/compose-extfields-sub.md %}
+
 ## Compose documentation
 
 - [User guide](/compose/index.md)

compose/reference/create.md

@@ -7,6 +7,7 @@ notoc: true
 
 ```
 Creates containers for a service.
+This command is deprecated. Use the `up` command with `--no-start` instead.
 
 Usage: create [options] [SERVICE...]
 

compose/reference/up.md

@@ -20,14 +20,15 @@ Options:
     --no-recreate              If containers already exist, don't recreate them.
                                Incompatible with --force-recreate.
     --no-build                 Don't build an image, even if it's missing.
+    --no-start                 Don't start the services after creating them.
     --build                    Build images before starting containers.
     --abort-on-container-exit  Stops all containers if any container was stopped.
                                Incompatible with -d.
     -t, --timeout TIMEOUT      Use this timeout in seconds for container shutdown
                                when attached or when containers are already
                                running. (default: 10)
-    --remove-orphans           Remove containers for services not defined in
+    --remove-orphans           Remove containers for services not
-                               the Compose file
+                               defined in the Compose file
     --exit-code-from SERVICE   Return the exit code of the selected service container.
                                Implies --abort-on-container-exit.
     --scale SERVICE=NUM        Scale SERVICE to NUM instances. Overrides the `scale`

release-notes/docker-compose.md

@@ -5,6 +5,63 @@ keywords: release notes, compose
 toc_max: 2
 ---
 
+## 1.17.0 (2017-11-03)
+
+### New features
+
+#### Compose file version 3.4
+
+- Introduced version 3.4 of the `docker-compose.yml` specification.
+  This version requires to be used with Docker Engine 17.06.0 or above.
+
+- Added support for `cache_from`, `network` and `target` options in build
+  configurations
+
+- Added support for the `order` parameter in the `update_config` section
+
+- Added support for setting a custom name in volume definitions using
+  the `name` parameter
+
+#### Compose file version 2.3
+
+- Added support for `shm_size` option in build configuration
+
+#### Compose file version 2.x
+
+- Added support for extension fields (`x-*`). Also available for v3.4 files
+
+#### All formats
+
+- Added new `--no-start` to the `up` command, allowing users to create all
+  resources (networks, volumes, containers) without starting services.
+  The `create` command is deprecated in favor of this new option
+
+### Bugfixes
+
+- Fixed a bug where `extra_hosts` values would be overridden by extension
+  files instead of merging together
+
+- Fixed a bug where the validation for v3.2 files would prevent using the
+  `consistency` field in service volume definitions
+
+- Fixed a bug that would cause a crash when configuration fields expecting
+  unique items would contain duplicates
+
+- Fixed a bug where mount overrides with a different mode would create a
+  duplicate entry instead of overriding the original entry
+
+- Fixed a bug where build labels declared as a list wouldn't be properly
+  parsed
+
+- Fixed a bug where the output of `docker-compose config` would be invalid
+  for some versions if the file contained custom-named external volumes
+
+- Improved error handling when issuing a build command on Windows using an
+  unsupported file version
+
+- Fixed an issue where networks with identical names would sometimes be
+  created when running `up` commands concurrently.
+
 ## 1.16.0 (2017-08-31)
 
 ### New features