Compose spec freshness (#23029)

aevesdocker · web-flow · commit 4c6f75f19fac · 2025-07-09T15:17:42.000+01:00
## Description Voila ## Related issues or tickets  ## Reviews   - [ ] Technical review - [ ] Editorial review - [ ] Product review
diff --git a/content/reference/compose-file/_index.md b/content/reference/compose-file/_index.md
@@ -45,7 +45,7 @@ aliases:
 
 The Compose Specification is the latest and recommended version of the Compose file format. It helps you define a [Compose file](/manuals/compose/intro/compose-application-model.md) which is used to configure your Docker application’s services, networks, volumes, and more.
 
-Legacy versions 2.x and 3.x of the Compose file format were merged into the Compose Specification. It is implemented in versions 1.27.0 and above (also known as Compose V2) of the Docker Compose CLI.
+Legacy versions 2.x and 3.x of the Compose file format were merged into the Compose Specification. It is implemented in versions 1.27.0 and above (also known as Compose v2) of the Docker Compose CLI.
 
 The Compose Specification on Docker Docs is the Docker Compose implementation. If you wish to implement your own version of the Compose Specification, see the [Compose Specification repository](https://github.com/compose-spec/compose-spec).
 
diff --git a/content/reference/compose-file/build.md b/content/reference/compose-file/build.md
@@ -49,7 +49,7 @@ services:
 
 When used to build service images from source, the Compose file creates three Docker images:
 
-* `example/webapp`: A Docker image is built using `webapp` sub-directory, within the Compose file's parent folder, as the Docker build context. Lack of a `Dockerfile` within this folder throws an error.
+* `example/webapp`: A Docker image is built using `webapp` sub-directory, within the Compose file's parent folder, as the Docker build context. Lack of a `Dockerfile` within this folder returns an error.
 * `example/database`: A Docker image is built using `backend` sub-directory within the Compose file parent folder. `backend.Dockerfile` file is used to define build steps, this file is searched relative to the context path, which means `..` resolves to the Compose file's parent folder, so `backend.Dockerfile` is a sibling file.
 * A Docker image is built using the `custom` directory with the user's `$HOME` as the Docker context. Compose displays a warning about the non-portable path used to build image.
 
diff --git a/content/reference/compose-file/configs.md b/content/reference/compose-file/configs.md
@@ -1,6 +1,6 @@
 ---
 title: Configs top-level elements
-description: Explore all the attributes the configs top-level element can have.
+description: Manage and share configuration data using the configs element in Docker Compose.
 keywords: compose, compose specification, configs, compose file reference
 aliases: 
  - /compose/compose-file/08-configs/
diff --git a/content/reference/compose-file/deploy.md b/content/reference/compose-file/deploy.md
@@ -132,7 +132,7 @@ services:
 `resources` configures physical resource constraints for container to run on platform. Those constraints can be configured
 as:
 
-- `limits`: The platform must prevent the container to allocate more.
+- `limits`: The platform must prevent the container from allocating more resources.
 - `reservations`: The platform must guarantee the container can allocate at least the configured amount.
 
 ```yml
@@ -270,7 +270,7 @@ deploy:
 
 ### `rollback_config`
 
-`rollback_config` configures how the service should be rollbacked in case of a failing update.
+`rollback_config` configures how the service should be rolled back in case of a failing update.
 
 - `parallelism`: The number of containers to rollback at a time. If set to 0, all containers rollback simultaneously.
 - `delay`: The time to wait between each container group's rollback (default 0s).
diff --git a/content/reference/compose-file/develop.md b/content/reference/compose-file/develop.md
@@ -43,8 +43,6 @@ services:
 
 ## Attributes
 
-<!-- vale Docker.HeadingSentenceCase = NO ) -->
-
 The `develop` subsection defines configuration options that are applied by Compose to assist you during development of a service with optimized workflows.
 
 ### `watch`
@@ -90,7 +88,7 @@ services:
 
 #### `ignore`
 
-The `ignore` attribute can be used to define a list of patterns for paths to be ignored. Any updated file
+The `ignore` attribute is used to define a list of patterns for paths to be ignored. Any updated file
 that matches a pattern, or belongs to a folder that matches a pattern, won't trigger services to be re-created. 
 The syntax is the same as `.dockerignore` file: 
 
@@ -106,7 +104,7 @@ for the `ignores` file, and values set in the Compose model are appended.
 
 It is sometimes easier to select files to be watched instead of declaring those that shouldn't be watched with `ignore`.
 
-The `include` attribute can be used to define a pattern, or a list of patterns, for paths to be considered for watching.
+The `include` attribute is used to define a pattern, or a list of patterns, for paths to be considered for watching.
 Only files that match these patterns will be considered when applying a watch rule. The syntax is the same as `ignore`.
 
 ```yaml
@@ -117,10 +115,15 @@ services:
       watch: 
         # rebuild image and recreate service
         - path: ./src
-          include: *.go  
+          include: "*.go"  
           action: rebuild
 ```
 
+> [!NOTE]
+> 
+> In many cases `include` patterns start with a wildcard (`*`) character. This has special meaning in YAML syntax
+> to define an [alias node](https://yaml.org/spec/1.2.2/#alias-nodes) so you have to wrap pattern expression with quotes.
+
 #### `path`
 
 `path` attribute defines the path to source code (relative to the project directory) to monitor for changes. Updates to any file
diff --git a/content/reference/compose-file/extension.md b/content/reference/compose-file/extension.md
@@ -1,6 +1,6 @@
 ---
 title: Extensions
-description: Understand how to use extensions
+description: Define and reuse custom fragments with extensions in Docker Compose
 keywords: compose, compose specification, extensions, compose file reference
 aliases: 
  - /compose/compose-file/11-extension/
@@ -117,7 +117,7 @@ services:
 >
 > In the example above, the environment variables are declared using the `FOO: BAR` mapping syntax, while the sequence syntax `- FOO=BAR` is only valid when no fragments are involved.
 
-## Informative Historical Notes
+## Informative historical notes
 
 This section is informative. At the time of writing, the following prefixes are known to exist:
 
diff --git a/content/reference/compose-file/fragments.md b/content/reference/compose-file/fragments.md
@@ -1,6 +1,6 @@
 ---
 title: Fragments
-description: Understand how to use fragments
+description: Reuse configuration with YAML anchors and fragments
 keywords: compose, compose specification, fragments, compose file reference
 aliases: 
  - /compose/compose-file/10-fragments/
diff --git a/content/reference/compose-file/include.md b/content/reference/compose-file/include.md
@@ -1,6 +1,7 @@
 ---
-title: Include
-description: Learn about include
+linkTitle: Include
+title: Use include to modularize Compose files
+description: Reference external Compose files using the include top-level element
 keywords: compose, compose specification, include, compose file reference
 aliases:
  - /compose/compose-file/14-include/
@@ -9,10 +10,10 @@ weight: 110
 
 {{< summary-bar feature_name="Composefile include" >}}
 
-A Compose application can declare dependency on another Compose application. This is useful if:
+You can reuse and modularize Docker Compose configurations by including other Compose files. This is useful if:
 - You want to reuse other Compose files.
 - You need to factor out parts of your application model into separate Compose files so they can be managed separately or shared with others.
-- Teams need to keep a Compose file reasonably complicated for the limited amount of resources it has to declare for its own sub-domain within a larger deployment.
+- Teams need to maintain a Compose file with only necessary complexity for the limited amount of resources it has to declare for its own sub-domain within a larger deployment.
 
 The `include` top-level section is used to define the dependency on another Compose application, or sub-domain.
 Each path listed in the `include` section is loaded as an individual Compose application model, with its own project directory, in order to resolve relative paths.
diff --git a/content/reference/compose-file/interpolation.md b/content/reference/compose-file/interpolation.md
@@ -1,6 +1,6 @@
 ---
 title: Interpolation
-description: Learn about interpolation
+description: Substitute environment variables in Docker Compose files using interpolation syntax.
 keywords: compose, compose specification, interpolation, compose file reference
 aliases: 
  - /compose/compose-file/12-interpolation/
diff --git a/content/reference/compose-file/merge.md b/content/reference/compose-file/merge.md
@@ -1,6 +1,7 @@
 ---
-title: Merge
-description: Learn about merging rules
+linkTitle: Merge
+title: Merge Compose files
+description: Understand how Docker Compose merges multiple files and resolves conflicts
 keywords: compose, compose specification, merge, compose file reference
 aliases: 
  - /compose/compose-file/13-merge/
diff --git a/content/reference/compose-file/models.md b/content/reference/compose-file/models.md
@@ -2,7 +2,7 @@
 title: Models
 description: Learn about the models top-level element
 keywords: compose, compose specification, models, compose file reference
-weight: 120
+weight: 130
 ---
 
 {{< summary-bar feature_name="Compose models" >}}
diff --git a/content/reference/compose-file/networks.md b/content/reference/compose-file/networks.md
@@ -1,6 +1,7 @@
 ---
-title: Networks top-level elements
-description: Explore all the attributes the networks top-level element can have.
+linkTitle: Networks
+title: Define and manage networks in Docker Compose
+description: Learn how to configure and control networks using the top-level networks element in Docker Compose.
 keywords: compose, compose specification, networks, compose file reference
 aliases:
  - /compose/compose-file/06-networks/
@@ -60,7 +61,7 @@ networks:
     driver: custom-driver
 ```
 
-The advanced example shows a Compose file which defines two custom networks. The `proxy` service is isolated from the `db` service, because they do not share a network in common. Only `app` can talk to both.
+This example shows a Compose file which defines two custom networks. The `proxy` service is isolated from the `db` service, because they do not share a network in common. Only `app` can talk to both.
 
 ## The default network
 
@@ -170,7 +171,7 @@ Compose doesn't attempt to create these networks, and returns an error if one do
  - All other attributes apart from name are irrelevant. If Compose detects any other attribute, it rejects the Compose file as invalid.
 
 In the following example, `proxy` is the gateway to the outside world. Instead of attempting to create a network, Compose
-queries the platform for an existing network simply called `outside` and connects the
+queries the platform for an existing network called `outside` and connects the
 `proxy` service's containers to it.
 
 ```yml
diff --git a/content/reference/compose-file/profiles.md b/content/reference/compose-file/profiles.md
@@ -1,5 +1,6 @@
 ---
-title: Profiles
+linkTitle: Profiles
+title: Learn how to use profiles in Docker Compose
 description: Learn about profiles
 keywords: compose, compose specification, profiles, compose file reference
 aliases: 
@@ -52,7 +53,7 @@ services:
 
 In the above example:
 
-- If the Compose application model is parsed with no profile enabled, it only contains the `web` service.
+- If the Compose application model is parsed when no profile is enabled, it only contains the `web` service.
 - If the profile `test` is enabled, the model contains the services `test_lib` and `coverage_lib`, and service `web`, which is always enabled.
 - If the profile `debug` is enabled, the model contains both `web` and `debug_lib` services, but not `test_lib` and `coverage_lib`,
   and as such the model is invalid regarding the `depends_on` constraint of `debug_lib`.
@@ -68,4 +69,4 @@ In the above example:
   profile `debug` is automatically enabled and service `test_lib` is pulled in as a dependency starting both
   services `debug_lib` and `test_lib`.
 
-See how you can use `profiles` in [Docker Compose](/manuals/compose/how-tos/profiles.md).
+Learn how to use `profiles` in [Docker Compose](/manuals/compose/how-tos/profiles.md).
diff --git a/content/reference/compose-file/secrets.md b/content/reference/compose-file/secrets.md
@@ -1,5 +1,5 @@
 ---
-title: Secrets top-level elements
+title: Secrets
 description: Explore all the attributes the secrets top-level element can have.
 keywords: compose, compose specification, secrets, compose file reference
 aliases: 
diff --git a/content/reference/compose-file/services.md b/content/reference/compose-file/services.md
@@ -1,5 +1,6 @@
 ---
-title: Services top-level elements
+linkTitle: Services
+title: Define services in Docker Compose
 description: Explore all the attributes the services top-level element can have.
 keywords: compose, compose specification, services, compose file reference
 aliases:
@@ -1290,7 +1291,7 @@ There is a performance penalty for applications that swap memory to disk often.
 - If `memswap_limit` is unset, and `memory` is set, the container can use as much swap as the `memory` setting, if the host container has swap memory configured. For instance, if `memory`="300m" and `memswap_limit` is not set, the container can use 600m in total of memory and swap.
 - If `memswap_limit` is explicitly set to -1, the container is allowed to use unlimited swap, up to the amount available on the host system.
 
-### models
+### `models`
 
 {{< summary-bar feature_name="Compose models" >}}
 
@@ -1358,7 +1359,7 @@ services:
 ```
 For more information about the `networks` top-level element, see [Networks](networks.md).
 
-### Implicit default network
+#### Implicit default network
 
 If `networks` is empty or absent from the Compose file, Compose considers an implicit definition for the service to be
 connected to the `default` network:
@@ -1674,7 +1675,7 @@ expressed in the short form.
 - `protocol`: The port protocol (`tcp` or `udp`). Defaults to `tcp`.
 - `app_protocol`: The application protocol (TCP/IP level 4 / OSI level 7) this port is used for. This is optional and can be used as a hint for Compose to offer richer behavior for protocols that it understands. Introduced in Docker Compose version [2.26.0](/manuals/compose/releases/release-notes.md#2260).
 - `mode`: Specifies how the port is published in a Swarm setup. If set to `host`, it publishes the port on every node in Swarm. If set to `ingress`, it allows load balancing across the nodes in Swarm. Defaults to `ingress`.
-- `name`: A human-readable name for the port, used to document it's usage within the service.
+- `name`: A human-readable name for the port, used to document its usage within the service.
 
 ```yml
 ports:
@@ -1783,12 +1784,12 @@ The mechanism used by Compose to delegate the service lifecycle to an external b
 
 For more information on using the `provider` attribute, see [Use provider services](/manuals/compose/how-tos/provider-services.md).
 
-### `type`
+#### `type`
 
 `type` attribute is required. It defines the external component used by Compose to manage setup and tear down lifecycle
 events.
 
-### `options`
+#### `options`
 
 `options` are specific to the selected provider and not validated by the compose specification
 
diff --git a/content/reference/compose-file/version-and-name.md b/content/reference/compose-file/version-and-name.md
@@ -9,17 +9,19 @@ weight: 10
 
 ## Version top-level element (obsolete)
 
-The top-level `version` property is defined by the Compose Specification for backward compatibility. It is only informative and you'll receive a warning message that it is obsolete if used. 
+> [!IMPORTANT]
+>
+> The top-level `version` property is defined by the Compose Specification for backward compatibility. It is only informative and you'll receive a warning message that it is obsolete if used. 
 
-Compose doesn't use `version` to select an exact schema to validate the Compose file, but
-prefers the most recent schema when it's implemented.
+Compose always uses the most recent schema to validate the Compose file, regardless of the `version` field.
 
 Compose validates whether it can fully parse the Compose file. If some fields are unknown, typically
 because the Compose file was written with fields defined by a newer version of the Specification, you'll receive a warning message. 
 
 ## Name top-level element
 
 The top-level `name` property is defined by the Compose Specification as the project name to be used if you don't set one explicitly.
+
 Compose offers a way for you to override this name, and sets a
 default project name to be used if the top-level `name` element is not set.
 
diff --git a/content/reference/compose-file/volumes.md b/content/reference/compose-file/volumes.md
@@ -1,6 +1,7 @@
 ---
-title: Volumes top-level element
-description: Explore all the attributes the volumes top-level element can have.
+linkTitle: Volumes 
+title: Define and manage volumes in Docker Compose
+description: Control how volumes are declared and shared between services using the top-level volumes element.
 keywords: compose, compose specification, volumes, compose file reference
 aliases: 
  - /compose/compose-file/07-volumes/
