Reference compose spec in compose file formats

Signed-off-by: aiordache <anca.iordache@docker.com>

_includes/content/compose-matrix.md

@@ -2,6 +2,7 @@ This table shows which Compose file versions support specific Docker releases.
 
 | **Compose file format** | **Docker Engine release** |
 |  -------------------    |    ------------------     |
+|  Compose specification  |       19.03.0+            |
 |      3.8                |       19.03.0+            |
 |      3.7                |       18.06.0+            |
 |      3.6                |       18.02.0+            |
@@ -25,3 +26,5 @@ do not necessarily 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.
+
+The latest Compose file format is defined by the [Compose Specification](https://github.com/compose-spec/compose-spec/blob/master/spec.md){:target="_blank" rel="noopener" class="_"} and is implemented by Docker Compose **1.27.0+**).

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

@@ -1,6 +1,6 @@
 ---
 description: Compose file reference
-keywords: fig, composition, compose version 3, docker
+keywords: fig, composition, compose version 2, docker
 title: Compose file version 2 reference
 toc_max: 4
 toc_min: 1

compose/compose-file/compose-file-v3.md

@@ -1,9 +1,6 @@
 ---
 description: Compose file reference
-keywords: fig, composition, compose, docker
+keywords: fig, composition, compose version 3, docker
-redirect_from:
-- /compose/yml
-- /compose/compose-file-v3/
 title: Compose file version 3 reference
 toc_max: 4
 toc_min: 1

compose/compose-file/compose-versioning.md

@@ -11,7 +11,8 @@ The Compose file formats are now described in these references, specific to each
 
 | **Reference file**                                    | **What changed in this version** |
 |:------------------------------------------------------|:---------------------------------|
-| [Version 3](index.md) (most current, and recommended) | [Version 3 updates](#version-3)  |
+| [Compose Specification](index.md) (most current, and recommended) | [Versioning](compose-versioning.md#versioning)  |
+| [Version 3](compose-file-v3.md)                       | [Version 3 updates](#version-3)  |
 | [Version 2](compose-file-v2.md)                       | [Version 2 updates](#version-2)  |
 | [Version 1](compose-file-v1.md)                       | [Version 1 updates](#version-1)  |
 
@@ -41,17 +42,17 @@ For details on versions and how to upgrade, see
 
 ## Versioning
 
-There are currently three versions of the Compose file format:
+There are three legacy versions of the Compose file format:
 
-- Version 1, the legacy format. This is specified by
+- Version 1. This is specified by omitting a `version` key at the root of the YAML.
-omitting a `version` key at the root of the YAML.
 
 - Version 2.x. This is specified with a `version: '2'` or `version: '2.1'`, etc., entry at the root of the YAML.
 
-- Version 3.x, the latest and recommended version, designed to
+- Version 3.x, designed to be cross-compatible between Compose and the Docker Engine's
-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.
 
+The latest and recommended version of the Compose file format is defined by the [Compose Specification](https://github.com/compose-spec/compose-spec/blob/master/spec.md). This format merges the 2.x and 3.x versions and is implemented by **Compose 1.27.0+**.
+
 > ### v2 and v3 Declaration
 >
 > **Note**: When specifying the Compose file version to use, make sure to
@@ -538,7 +539,7 @@ flag with the `config` command.
 
 
 ## Compose file format references
-
+- [Compose Specification](index.md)
-- [Compose file version 3](index.md)
+- [Compose file version 3](compose-file-v3.md)
 - [Compose file version 2](compose-file-v2.md)
 - [Compose file version 1](compose-file-v1.md)

compose/compose-file/index.md

@@ -0,0 +1,30 @@
+---
+description: Compose file reference
+keywords: fig, composition, compose, docker
+redirect_from:
+- /compose/yml
+title: Compose file
+toc_max: 4
+toc_min: 1
+---
+
+## Reference and guidelines
+
+These topics describe the Docker Compose implementation of the Compose format.
+Docker Compose **1.27.0+** implements the format defined by the [Compose Specification](https://github.com/compose-spec/compose-spec/blob/master/spec.md). Previous Docker Compose versions have support for several Compose file formats – 1, 2, 2.x, and 3.x. The Compose specification is an unified 2.x and 3.x file format, aggregating properties accross these formats.
+
+## Compose and Docker compatibility matrix
+
+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 documentation
+
+- [User guide](../index.md)
+- [Installing Compose](../install.md)
+- [Compose file versions and upgrading](compose-versioning.md)
+- [Sample apps with Compose](../samples-for-compose.md)
+- [Command line reference](../reference/index.md)

compose/index.md

@@ -33,7 +33,7 @@ so they can be run together in an isolated environment.
 A `docker-compose.yml` looks like this:
 
 ```yaml
-version: "{{ site.compose_file_v3 }}"
+version: "{{ site.compose_file_v3 }}"  # optional since v1.27.0
 services:
   web:
     build: .