From e295a6e6cb86d3c8ebe08eaa9155efe5a599e077 Mon Sep 17 00:00:00 2001
From: Sebastiaan van Stijn <thaJeztah@users.noreply.github.com>
Date: Fri, 12 Apr 2019 15:25:47 +0200
Subject: [PATCH] Use site parameter to use latest compose file versions in
 examples (#8630)

* Use site parameter to use latest compose file versions in examples

Make sure that examples use the latest version of the compose file
format, to encourage using the latest version, and to prevent
users from running into "not supported by this version" problems
when copy/pasting, and combining examples that use different
versions.

Also add a note about `version: x` not being equivalent to
`version: x.latest`.

Note that there are still some examples using fixed versions
in the UCP sections; we need to evaluate those to make sure
the right (and supported) versions are used for UCP (which may
be different than "latest").

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

* Address some v3/v2 issues, and YAML syntax error

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

* Minor edit

* Final updates

- Added note around v2 and v3 versioning
- Updated note for v3 to match the v2 update
---
 _config.yml                                |  2 +
 _config_authoring.yml                      |  2 +
 compose/compose-file/compose-file-v2.md    | 36 ++++----
 compose/compose-file/compose-versioning.md | 46 ++++++++--
 compose/compose-file/index.md              | 98 +++++++++++-----------
 5 files changed, 111 insertions(+), 73 deletions(-)

diff --git a/_config.yml b/_config.yml
index 1d4cac4388..004db5872e 100644
--- a/_config.yml
+++ b/_config.yml
@@ -23,6 +23,8 @@ latest_engine_api_version: "1.39"
 docker_ce_version: "18.09"
 docker_ee_version: "18.09"
 compose_version: "1.24.0"
+compose_file_v3: "3.7"
+compose_file_v2: "2.4"
 machine_version: "0.16.0"
 distribution_version: "2.6"
 dtr_version: "2.6"
diff --git a/_config_authoring.yml b/_config_authoring.yml
index 03abb3e5db..ca8a6212a8 100644
--- a/_config_authoring.yml
+++ b/_config_authoring.yml
@@ -23,6 +23,8 @@ latest_engine_api_version: "1.39"
 docker_ce_version: "18.09"
 docker_ee_version: "18.09"
 compose_version: "1.24.0"
+compose_file_v3: "3.7"
+compose_file_v2: "2.4"
 machine_version: "0.16.0"
 distribution_version: "2.6"
 dtr_version: "2.6"
diff --git a/compose/compose-file/compose-file-v2.md b/compose/compose-file/compose-file-v2.md
index fbd903d624..5867968a25 100644
--- a/compose/compose-file/compose-file-v2.md
+++ b/compose/compose-file/compose-file-v2.md
@@ -50,7 +50,7 @@ definition in version 2.
 
 A set of configuration options to set block IO limits for this service.
 
-    version: '2.2'
+    version: "{{ site.compose_file_v2 }}"
     services:
       foo:
         image: busybox
@@ -393,7 +393,7 @@ Express dependency between services, which has two effects:
 
 Simple example:
 
-    version: '2'
+    version: "{{ site.compose_file_v2 }}"
     services:
       web:
         build: .
@@ -418,7 +418,7 @@ the healthcheck) before starting.
 
 Example:
 
-    version: '2.1'
+    version: "{{ site.compose_file_v2 }}"
     services:
       web:
         build: .
@@ -667,7 +667,7 @@ details.
 A full example:
 
 ```
-version: '2'
+version: "{{ site.compose_file_v2 }}"
 services:
   myservice:
     image: alpine
@@ -741,14 +741,14 @@ Run an init inside the container that forwards signals and reaps processes.
 Either set a boolean value to use the default `init`, or specify a path to
 a custom one.
 
-    version: '2.2'
+    version: "{{ site.compose_file_v2 }}"
     services:
       web:
         image: alpine:latest
         init: true
 
 
-    version: '2.2'
+    version: "{{ site.compose_file_v2 }}"
     services:
       web:
         image: alpine:latest
@@ -885,7 +885,7 @@ The general format is shown here.
 
 In the example below, three services are provided (`web`, `worker`, and `db`), along with two networks (`new` and `legacy`). The `db` service is reachable at the hostname `db` or `database` on the `new` network, and at `db` or `mysql` on the `legacy` network.
 
-    version: '2'
+    version: "{{ site.compose_file_v2 }}"
 
     services:
       web:
@@ -920,7 +920,7 @@ The corresponding network configuration in the [top-level networks section](#net
 
 An example:
 
-    version: '2.1'
+    version: "{{ site.compose_file_v2 }}"
 
     services:
       app:
@@ -954,7 +954,7 @@ managed by docker (IPAM driver).
 
 Example usage:
 
-    version: '2.1'
+    version: "{{ site.compose_file_v2 }}"
     services:
       app:
         image: busybox
@@ -977,7 +977,7 @@ In the following example, the `app` service connects to `app_net_1` first
 as it has the highest priority. It then connects to `app_net_3`, then
 `app_net_2`, which uses the default priority value of `0`.
 
-    version: '2.3'
+    version: "{{ site.compose_file_v2 }}"
     services:
       app:
         image: busybox
@@ -1216,7 +1216,7 @@ expressed in the short form.
 
 
 ```none
-version: "2.3"
+version: "{{ site.compose_file_v2 }}"
 services:
   web:
     image: nginx:alpine
@@ -1380,7 +1380,7 @@ Here's an example of a two-service setup where a database's data directory is
 shared with another service as a volume so that it can be periodically backed
 up:
 
-    version: "2.2"
+    version: "{{ site.compose_file_v2 }}"
 
     services:
       db:
@@ -1433,7 +1433,7 @@ In the example below, instead of attempting to create a volume called
 `[projectname]_data`, Compose looks for an existing volume simply
 called `data` and mount it into the `db` service's containers.
 
-    version: '2'
+    version: "{{ site.compose_file_v2 }}"
 
     services:
       db:
@@ -1484,14 +1484,14 @@ conflicting with those used by other software.
 
 Set a custom name for this volume.
 
-    version: '2.1'
+    version: "{{ site.compose_file_v2 }}"
     volumes:
       data:
         name: my-app-data
 
 It can also be used in conjunction with the `external` property:
 
-    version: '2.1'
+    version: "{{ site.compose_file_v2 }}"
     volumes:
       data:
         external: true
@@ -1609,7 +1609,7 @@ attempting to create a network called `[projectname]_outside`, Compose
 looks for an existing network simply called `outside` and connect the `proxy`
 service's containers to it.
 
-    version: '2'
+    version: "{{ site.compose_file_v2 }}"
 
     services:
       proxy:
@@ -1644,14 +1644,14 @@ Not supported for version 2 `docker-compose` files. Use
 
 Set a custom name for this network.
 
-    version: '2.1'
+    version: "{{ site.compose_file_v2 }}"
     networks:
       network1:
         name: my-app-net
 
 It can also be used in conjunction with the `external` property:
 
-    version: '2.1'
+    version: "{{ site.compose_file_v2 }}"
     networks:
       network1:
         external: true
diff --git a/compose/compose-file/compose-versioning.md b/compose/compose-file/compose-versioning.md
index 74b714401e..724f50cf81 100644
--- a/compose/compose-file/compose-versioning.md
+++ b/compose/compose-file/compose-versioning.md
@@ -52,6 +52,12 @@ omitting a `version` key at the root of the YAML.
 be cross-compatible between Compose and the Docker Engine's
 [swarm mode](/engine/swarm/index.md). This is specified with a `version: '3'` or `version: '3.1'`, etc., entry at the root of the YAML.
 
+> ### v2 and v3 Declaration
+>
+> **Note**: When specifying the Compose file version to use, make sure to
+> specify both the _major_ and _minor_ numbers. If no minor version is given,
+> `0` is used by default and not the latest minor version.
+
 
 The [Compatibility Matrix](#compatibility-matrix) shows Compose file versions mapped to Docker Engine releases.
 
@@ -121,9 +127,24 @@ discoverable at a hostname that's the same as the service name. This means
 [links](compose-file-v2.md#links) are largely unnecessary. For more details, see
 [Networking in Compose](compose-file-v2.md#networking.md).
 
+> **Note**: When specifying the Compose file version to use, make sure to
+> specify both the _major_ and _minor_ numbers. If no minor version is given,
+> `0` is used by default and not the latest minor version. As a result, features added in
+> later versions will not be supported. For example:
+>
+> ```yaml
+> version: "2"
+> ```
+> 
+> is equivalent to:
+> 
+> ```yaml
+> version: "2.0"
+> ```
+
 Simple example:
 
-    version: '2'
+    version: "{{ site.compose_file_v2 }}"
     services:
       web:
         build: .
@@ -136,7 +157,7 @@ Simple example:
 
 A more extended example, defining volumes and networks:
 
-    version: '2'
+    version: "{{ site.compose_file_v2 }}"
     services:
       web:
         build: .
@@ -169,7 +190,7 @@ Several other options were added to support networking, such as:
 * The [`depends_on`](compose-file-v2.md#depends_on) option can be used in place of links to indicate dependencies
 between services and startup order.
 
-      version: '2'
+      version: "{{ site.compose_file_v2 }}"
       services:
         web:
           build: .
@@ -259,6 +280,21 @@ the [upgrading](#upgrading) guide for how to migrate away from these.
 
 - Added: [deploy](/compose/compose-file/index.md#deploy)
 
+> **Note**: When specifying the Compose file version to use, make sure to
+> specify both the _major_ and _minor_ numbers. If no minor version is given,
+> `0` is used by default and not the latest minor version. As a result, features added in
+> later versions will not be supported. For example:
+>
+> ```yaml
+> version: "3"
+> ```
+> 
+> is equivalent to:
+> 
+> ```yaml
+> version: "3.0"
+> ```
+
 ### Version 3.3
 
 An upgrade of [version 3](#version-3) that introduces new parameters only
@@ -327,7 +363,7 @@ several options have been removed:
     [top-level `volumes` option](/compose/compose-file/index.md#volume-configuration-reference)
     and specify the driver there.
 
-        version: "3"
+        version: "{{ site.compose_file_v3 }}"
         services:
           db:
             image: postgres
@@ -422,7 +458,7 @@ It's more complicated if you're using particular configuration features:
     named volume called `data`, you must declare a `data` volume in your
     top-level `volumes` section. The whole file might look like this:
 
-        version: '2'
+        version: "{{ site.compose_file_v2 }}"
         services:
           db:
             image: postgres
diff --git a/compose/compose-file/index.md b/compose/compose-file/index.md
index 1270fcc8f3..f30b340823 100644
--- a/compose/compose-file/index.md
+++ b/compose/compose-file/index.md
@@ -30,7 +30,7 @@ how to upgrade, see **[About versions and upgrading](compose-versioning.md)**.
     <i class="chevron fa fa-fw"></i></div>
     <div class="collapse block" id="collapseSample1">
 <pre><code>
-version: "3"
+version: "{{ site.compose_file_v3 }}"
 services:
 
   redis:
@@ -182,7 +182,7 @@ Configuration options that are applied at build time.
 context:
 
 ```yaml
-version: '3'
+version: "{{ site.compose_file_v3 }}"
 services:
   webapp:
     build: ./dir
@@ -192,7 +192,7 @@ Or, as an object with the path specified under [context](#context) and
 optionally [Dockerfile](#dockerfile) and [args](#args):
 
 ```yaml
-version: '3'
+version: "{{ site.compose_file_v3 }}"
 services:
   webapp:
     build:
@@ -447,7 +447,7 @@ the stack deployment fails with a `config not found` error.
 >  of the compose file format.
 
 ```yaml
-version: "3.3"
+version: "{{ site.compose_file_v3 }}"
 services:
   redis:
     image: redis:latest
@@ -489,7 +489,7 @@ to `103`. The `redis` service does not have access to the `my_other_config`
 config.
 
 ```yaml
-version: "3.3"
+version: "{{ site.compose_file_v3 }}"
 services:
   redis:
     image: redis:latest
@@ -573,7 +573,7 @@ behaviors:
 Simple example:
 
 ```yaml
-version: '3'
+version: "{{ site.compose_file_v3 }}"
 services:
   web:
     build: .
@@ -609,7 +609,7 @@ only takes effect when deploying to a [swarm](/engine/swarm/index.md) with
 ignored by `docker-compose up` and `docker-compose run`.
 
 ```yaml
-version: '3'
+version: "{{ site.compose_file_v3 }}"
 services:
   redis:
     image: redis:alpine
@@ -645,7 +645,7 @@ in cases where you want to use your own load balancer, or for Hybrid
 Windows and Linux applications.
 
 ```yaml
-version: "3.3"
+version: "{{ site.compose_file_v3 }}"
 
 services:
   wordpress:
@@ -694,7 +694,7 @@ Specify labels for the service. These labels are *only* set on the service,
 and *not* on any containers for the service.
 
 ```yaml
-version: "3"
+version: "{{ site.compose_file_v3 }}"
 services:
   web:
     image: web
@@ -706,7 +706,7 @@ services:
 To set labels on containers instead, use the `labels` key outside of `deploy`:
 
 ```yaml
-version: "3"
+version: "{{ site.compose_file_v3 }}"
 services:
   web:
     image: web
@@ -724,7 +724,7 @@ in the [swarm](/engine/swarm/) topics.)
 
 
 ```yaml
-version: '3'
+version: "{{ site.compose_file_v3 }}"
 services:
   worker:
     image: dockersamples/examplevotingapp_worker
@@ -737,7 +737,7 @@ services:
 Specify placement of constraints and preferences. See the docker service create documentation for a full description of the syntax and available types of [constraints](/engine/reference/commandline/service_create.md#specify-service-constraints-constraint) and [preferences](/engine/reference/commandline/service_create.md#specify-service-placement-preferences-placement-pref).
 
 ```yaml
-version: '3.3'
+version: "{{ site.compose_file_v3 }}"
 services:
   db:
     image: postgres
@@ -756,7 +756,7 @@ If the service is `replicated` (which is the default), specify the number of
 containers that should be running at any given time.
 
 ```yaml
-version: '3'
+version: "{{ site.compose_file_v3 }}"
 services:
   worker:
     image: dockersamples/examplevotingapp_worker
@@ -785,7 +785,7 @@ In this general example, the `redis` service is constrained to use no more than
 and has `20M` of memory and `0.25` CPU time reserved (as always available to it).
 
 ```yaml
-version: '3'
+version: "{{ site.compose_file_v3 }}"
 services:
   redis:
     image: redis:alpine
@@ -841,7 +841,7 @@ Configures if and how to restart containers when they exit. Replaces
   decide immediately).
 
 ```yaml
-version: "3"
+version: "{{ site.compose_file_v3 }}"
 services:
   redis:
     image: redis:alpine
@@ -884,7 +884,7 @@ updates.
 file format.
 
 ```yaml
-version: '3.4'
+version: "{{ site.compose_file_v3 }}"
 services:
   vote:
     image: dockersamples/examplevotingapp_vote:before
@@ -954,7 +954,7 @@ behaviors:
 Simple example:
 
 ```yaml
-version: '3'
+version: "{{ site.compose_file_v3 }}"
 services:
   web:
     build: .
@@ -986,6 +986,9 @@ Custom DNS servers. Can be a single value or a list.
 
 ```yaml
 dns: 8.8.8.8
+```
+
+```yaml
 dns:
   - 8.8.8.8
   - 9.9.9.9
@@ -1256,7 +1259,7 @@ Either set a boolean value to use the default `init`, or specify a path to
 a custom one.
 
 ```yaml
-version: '3.7'
+version: "{{ site.compose_file_v3 }}"
 services:
   web:
     image: alpine:latest
@@ -1393,7 +1396,7 @@ files are removed to allow storage of new logs.
 Here is an example `docker-compose.yml` file that limits logging storage:
 
 ```yaml
-version: '3.7'
+version: "{{ site.compose_file_v3 }}"
 services:
   some-service:
     image: some-service
@@ -1474,16 +1477,16 @@ the hostname `db` or `database` on the `new` network, and at `db` or `mysql` on
 the `legacy` network.
 
 ```yaml
-version: '2'
+version: "{{ site.compose_file_v3 }}"
 
 services:
   web:
-    build: ./web
+    image: "nginx:alpine"
     networks:
       - new
 
   worker:
-    build: ./worker
+    image: "my-worker-image:latest"
     networks:
       - legacy
 
@@ -1508,21 +1511,20 @@ Specify a static IP address for containers for this service when joining the net
 
 The corresponding network configuration in the
 [top-level networks section](#network-configuration-reference) must have an
-`ipam` block with subnet configurations covering each static address. If IPv6
-addressing is desired, the [`enable_ipv6`](#enableipv6) option must be set, and
-you must use a version 2.x Compose file, such as the one below.
+`ipam` block with subnet configurations covering each static address.
 
-> **Note**: These options do not currently work in swarm mode.
+> If IPv6 addressing is desired, the [`enable_ipv6`](compose-file-v2.md##enable_ipv6)
+> option must be set, and you must use a [version 2.x Compose file](compose-file-v2.md#ipv4_address-ipv6_address).
+> _IPv6 options do not currently work in swarm mode_.
 
 An example:
 
 ```yaml
-version: '2.1'
+version: "{{ site.compose_file_v3 }}"
 
 services:
   app:
-    image: busybox
-    command: ifconfig
+    image: nginx:alpine
     networks:
       app_net:
         ipv4_address: 172.16.238.10
@@ -1530,15 +1532,11 @@ services:
 
 networks:
   app_net:
-    driver: bridge
-    enable_ipv6: true
     ipam:
       driver: default
       config:
-      -
-        subnet: 172.16.238.0/24
-      -
-        subnet: 2001:3984:3989::/64
+        - subnet: "172.16.238.0/24"
+        - subnet: "2001:3984:3989::/64"
 ```
 
 ### pid
@@ -1642,7 +1640,7 @@ command or by another stack deployment. If the external secret does not exist,
 the stack deployment fails with a `secret not found` error.
 
 ```yaml
-version: "3.1"
+version: "{{ site.compose_file_v3 }}"
 services:
   redis:
     image: redis:latest
@@ -1685,7 +1683,7 @@ to `103`. The `redis` service does not have access to the `my_other_secret`
 secret.
 
 ```yaml
-version: "3.1"
+version: "{{ site.compose_file_v3 }}"
 services:
   redis:
     image: redis:latest
@@ -1850,7 +1848,7 @@ for mounting a named volume. Named volumes must be listed under the top-level
 `volumes` key, as shown.
 
 ```yaml
-version: "3.2"
+version: "{{ site.compose_file_v3 }}"
 services:
   web:
     image: nginx:alpine
@@ -1927,7 +1925,7 @@ expressed in the short form.
 - `consistency`: the consistency requirements of the mount, one of `consistent` (host and container have identical view), `cached` (read cache, host view is authoritative) or `delegated` (read-write cache, container's view is authoritative)
 
 ```yaml
-version: "3.2"
+version: "{{ site.compose_file_v3 }}"
 services:
   web:
     image: nginx:alpine
@@ -1975,7 +1973,7 @@ configured as a named volume to persist the data on the swarm,
 _and_ is constrained to run only on `manager` nodes. Here is the relevant snip-it from that file:
 
 ```yaml
-version: "3"
+version: "{{ site.compose_file_v3 }}"
 services:
   db:
     image: postgres:9.4
@@ -2011,7 +2009,7 @@ are visible on the host.
 Here is an example of configuring a volume as `cached`:
 
 ```yaml
-version: '3'
+version: "{{ site.compose_file_v3 }}"
 services:
   php:
     image: php:7.1-fpm
@@ -2096,7 +2094,7 @@ shared with another service as a volume so that it can be periodically backed
 up:
 
 ```yaml
-version: "3"
+version: "{{ site.compose_file_v3 }}"
 
 services:
   db:
@@ -2158,7 +2156,7 @@ In the example below, instead of attempting to create a volume called
 called `data` and mount it into the `db` service's containers.
 
 ```yaml
-version: '3'
+version: "{{ site.compose_file_v3 }}"
 
 services:
   db:
@@ -2227,7 +2225,7 @@ volumes that contain special characters. The name is used as is
 and will **not** be scoped with the stack name.
 
 ```yaml
-version: '3.4'
+version: "{{ site.compose_file_v3 }}"
 volumes:
   data:
     name: my-app-data
@@ -2236,7 +2234,7 @@ volumes:
 It can also be used in conjunction with the `external` property:
 
 ```yaml
-version: '3.4'
+version: "{{ site.compose_file_v3 }}"
 volumes:
   data:
     external: true
@@ -2306,7 +2304,7 @@ Docker has already created automatically) and an alias that Compose can use
 network using the alias.
 
 ```yaml
-version: '3.7'
+version: "{{ site.compose_file_v3 }}"
 services:
   web:
     networks:
@@ -2448,7 +2446,7 @@ looks for an existing network simply called `outside` and connect the `proxy`
 service's containers to it.
 
 ```yaml
-version: '3'
+version: "{{ site.compose_file_v3 }}"
 
 services:
   proxy:
@@ -2473,7 +2471,7 @@ You can also specify the name of the network separately from the name used to
 refer to it within the Compose file:
 
 ```yaml
-version: '3.5'
+version: "{{ site.compose_file_v3 }}"
 networks:
   outside:
     external:
@@ -2489,7 +2487,7 @@ networks which contain special characters. The name is used as is
 and will **not** be scoped with the stack name.
 
 ```yaml
-version: '3.5'
+version: "{{ site.compose_file_v3 }}"
 networks:
   network1:
     name: my-app-net
@@ -2498,7 +2496,7 @@ networks:
 It can also be used in conjunction with the `external` property:
 
 ```yaml
-version: '3.5'
+version: "{{ site.compose_file_v3 }}"
 networks:
   network1:
     external: true