Use site parameter to use latest compose file versions in examples (docker#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 <[email protected]>

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

Signed-off-by: Sebastiaan van Stijn <[email protected]>

* Minor edit

* Final updates

- Added note around v2 and v3 versioning
- Updated note for v3 to match the v2 update

Author: thaJeztah

_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"

_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"

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

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