added links to Compose release versions, improved matrix description (#3580)

* added links to Compose release versions, improved matrix description

Signed-off-by: Victoria Bialas <victoria.bialas@docker.com>

* review comments, used include for matrix in all file references

Signed-off-by: Victoria Bialas <victoria.bialas@docker.com>

* incorporated review comments

Signed-off-by: Victoria Bialas <victoria.bialas@docker.com>

_includes/content/compose-matrix.md

@@ -1,13 +1,18 @@
-There are several versions of the Compose file format – 1, 2, 2.1 and 3. For
-details on versions and how to upgrade, see
-[Versioning](compose-versioning.md#versioning) and
-[Upgrading](compose-versioning.md#upgrading).
-
 This table shows which Compose file versions support specific Docker releases.
 
 | **Compose file format** | **Docker Engine release** |
 |  -------------------    |    ------------------     |
-|      3.0 ; 3.1          |       1.13.0+             |
+|      3.3                |       17.06.0+            |
+|      3.0 - 3.2          |       1.13.0+             |
+|      2.2                |       1.13.0+             |
 |      2.1                |       1.12.0+             |
 |      2.0                |       1.10.0+             |
 |      1.0                |       1.9.1.+             |
+
+In addition to Compose file format versions shown in the table, the Compose
+itself is on a release schedule, as shown in [Compose
+releases](https://github.com/docker/compose/releases/), but file format versions
+do not necessairly increment with each release. For example, Compose file format
+3.0 was first introduced in [Compose release
+1.10.0](https://github.com/docker/compose/releases/tag/1.10.0), and versioned
+gradually in subsequent releases.

compose/compose-file/compose-file-v1.md

@@ -13,9 +13,13 @@ toc_min: 1
 These topics describe version 1 of the Compose file format. This is the oldest
 version.
 
-For a Compose/Docker Engine compatibility matrix, and detailed guidelines on
+## Compose and Docker compatibility matrix
-versions and upgrading, see
+
-[Compose file versions and upgrading](compose-versioning.md).
+There are several versions of the Compose file format – 1, 2, 2.x, and 3.x The
+table below is a quick look. For full details on what each version includes and
+how to upgrade, see **[About versions and upgrading](compose-versioning.md)**.
+
+{% include content/compose-matrix.md %}
 
 ## Service configuration reference
 

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

@@ -12,9 +12,13 @@ toc_min: 1
 
 These topics describe version 2 of the Compose file format.
 
-For a Compose/Docker Engine compatibility matrix, and detailed guidelines on
+## Compose and Docker compatibility matrix
-versions and upgrading, see
+
-[Compose file versions and upgrading](compose-versioning.md).
+There are several versions of the Compose file format – 1, 2, 2.x, and 3.x The
+table below is a quick look. For full details on what each version includes and
+how to upgrade, see **[About versions and upgrading](compose-versioning.md)**.
+
+{% include content/compose-matrix.md %}
 
 ## Service configuration reference
 

compose/compose-file/compose-versioning.md

@@ -20,8 +20,25 @@ compatibility, and [how to upgrade](#upgrading).
 
 ## Compatibility matrix
 
+There are several versions of the Compose file format – 1, 2, 2.x, and 3.x
+
 {% include content/compose-matrix.md %}
 
+> Looking for more detail on Docker and Compose compatibility?
+>
+> We recommend keeping up-to-date with newer releases as much as possible.
+However, if you are using an older version of Docker and want to determine which
+Compose release is compatible, please refer to the [Compose release
+notes](https://github.com/docker/compose/releases/). Each set of release notes
+gives details on which versions of Docker Engine are supported, along
+with compatible Compose file format versions. (See also, the discussion in
+[issue #3404](https://github.com/docker/docker.github.io/issues/3404).)
+{: .note-vanilla}
+
+For details on versions and how to upgrade, see
+[Versioning](compose-versioning.md#versioning) and
+[Upgrading](compose-versioning.md#upgrading).
+
 ## Versioning
 
 There are currently three versions of the Compose file format:

compose/compose-file/index.md

@@ -14,9 +14,13 @@ toc_min: 1
 These topics describe version 3 of the Compose file format. This is the newest
 version.
 
-For a Compose/Docker Engine compatibility matrix, and detailed guidelines on
+## Compose and Docker compatibility matrix
-versions and upgrading, see
+
-[Compose file versions and upgrading](compose-versioning.md).
+There are several versions of the Compose file format – 1, 2, 2.x, and 3.x The
+table below is a quick look. For full details on what each version includes and
+how to upgrade, see **[About versions and upgrading](compose-versioning.md)**.
+
+{% include content/compose-matrix.md %}
 
 ## Compose file structure and examples