From 4021d76e8b6fd52cc940b94dbea4648ac718e01b Mon Sep 17 00:00:00 2001
From: Allie Sadler <102604716+aevesdocker@users.noreply.github.com>
Date: Mon, 16 Sep 2024 14:57:42 +0100
Subject: [PATCH] compose spec consistency (#20915)

* compose spec consistency

* fix links

* Update content/reference/compose-file/build.md

Co-authored-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>

---------

Co-authored-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
---
 content/reference/compose-file/build.md  |  7 ++++++-
 content/reference/compose-file/deploy.md | 23 ++++-------------------
 2 files changed, 10 insertions(+), 20 deletions(-)

diff --git a/content/reference/compose-file/build.md b/content/reference/compose-file/build.md
index d34afa8c4b..ec516cbb53 100644
--- a/content/reference/compose-file/build.md
+++ b/content/reference/compose-file/build.md
@@ -508,7 +508,12 @@ build:
 ```
 
 The image builder can then rely on this to mount the SSH key during build.
-For more information, see the [`RUN --mount=type=ssh` Dockerfile reference](/reference/dockerfile.md#run---mounttypessh).
+
+For illustration, [SSH mounts](https://github.com/moby/buildkit/blob/master/frontend/dockerfile/docs/reference.md#run---mounttypessh) can be used to mount the SSH key set by ID and access a secured resource:
+
+```console
+RUN --mount=type=ssh,id=myproject git clone ...
+```
 
 ### shm_size
 
diff --git a/content/reference/compose-file/deploy.md b/content/reference/compose-file/deploy.md
index 7b4cea9879..11fd5e911c 100644
--- a/content/reference/compose-file/deploy.md
+++ b/content/reference/compose-file/deploy.md
@@ -66,8 +66,7 @@ services:
 
 #### constraints
 
-`constraints` defines a required property the platform's node must fulfill to run the service container. It can be set either
-by a list or a map with string values.
+`constraints` defines a required property the platform's node must fulfill to run the service container. For a further example, see the [CLI reference docs](/reference/cli/docker/service/create.md#constraint).
 
 ```yml
 deploy:
@@ -76,30 +75,16 @@ deploy:
       - disktype=ssd
 ```
 
-```yml
-deploy:
-  placement:
-    constraints:
-      disktype: ssd
-```
-
 #### preferences
 
-`preferences` defines a property the platform's node should fulfill to run service container. It can be set either
-by a list or a map with string values.
+`preferences` defines a strategy (currently `spread` is the only supported strategy) to spread tasks evenly 
+over the values of the datacenter node label. For a further example, see the [CLI reference docs](/reference/cli/docker/service/create.md#placement-pref)
 
 ```yml
 deploy:
   placement:
     preferences:
-      - datacenter=us-east
-```
-
-```yml
-deploy:
-  placement:
-    preferences:
-      datacenter: us-east
+      - spread: node.labels.zone
 ```
 
 ### replicas