tweak reset and override examples

Signed-off-by: aevesdocker <allie.sadler@docker.com>
compose-spec · Feb 19, 2024 · 78b13c4 · 78b13c4
1 parent 1938efd
commit 78b13c4
Show file tree

Hide file tree

Showing 2 changed files with 72 additions and 62 deletions.
diff --git a/13-merge.md b/13-merge.md
@@ -141,41 +141,35 @@ For readability, it is recommended to explicitly set the attribute value to the
 array `[]` (with `!reset null` or `!reset []`) so that it is clear that resulting attribute will be
 cleared.
 
-Merging the following example YAML trees:
+A base `compose.yaml` file:
 
 ```yaml
 services:
-  foo:
-    build: 
-      dockerfile: foo.Dockerfile
-    read_only: true
-    environment:
-      FOO: BAR
+app:
+    image: myapp
     ports:
-      - "8080:80"            
+      - "8080:80"
+    environment:
+      FOO: BAR             
 ```
 
+And an `overide.compose.yaml` file:
+
 ```yaml
 services:
-  foo:
-    image: foo
-    build: !reset null
-    read_only: !reset false
+  app:
+    image: myapp
+    ports: !reset []
     environment:
       FOO: !reset null
-    ports: !reset []
 ```
 
-Result in a Compose application model equivalent to the YAML tree:
+Results in:
 
 ```yaml
 services:
-  foo:
-    image: foo
-    build: null
-    read_only: false
-    environment: {}
-    ports: []
+  app:
+    image: myapp
 ```
 
 ### Replace value
@@ -184,22 +178,33 @@ While `!reset` can be used to remove a declaration from a Compose file using an
 you to fully replace an attribute, bypassing the standard merge rules. A typical example is to fully replace a 
 resource definition, to rely on a distinct model but using the same name.
 
-Merging the following example YAML trees:
+A base `compose.yaml` file:
 
 ```yaml
-networks:
-  foo:
-    # this is production configuration
-    name: production-overlay-network
-    driver: overlay
-    driver-opts: (...)
+services:
+app:
+    image: myapp
+    ports:
+      - "8080:80"
 ```
 
+To remove the original port, but expose a new one, the following override file is used:
+
 ```yaml
-networks:
-  # this is development configuration
-  foo: !override {}
+services:
+  app:
+    ports: !override
+      - "8443:443" 
 ```
 
-Results in a Compose application model equivalent to the override YAML tree.
+This results in: 
+
+```yaml
+services:
+  app:
+    image: myapp
+    ports:
+      - "8443:443" 
+```
 
+If `!override` had not been used, both `8080:80` and `8443:443` would be exposed as per the [merging rules outlined above](#sequence). 
diff --git a/spec.md b/spec.md
@@ -2972,41 +2972,35 @@ For readability, it is recommended to explicitly set the attribute value to the
 array `[]` (with `!reset null` or `!reset []`) so that it is clear that resulting attribute will be
 cleared.
 
-Merging the following example YAML trees:
+A base `compose.yaml` file:
 
 ```yaml
 services:
-  foo:
-    build: 
-      dockerfile: foo.Dockerfile
-    read_only: true
-    environment:
-      FOO: BAR
+app:
+    image: myapp
     ports:
-      - "8080:80"            
+      - "8080:80"
+    environment:
+      FOO: BAR             
 ```
 
+And an `overide.compose.yaml` file:
+
 ```yaml
 services:
-  foo:
-    image: foo
-    build: !reset null
-    read_only: !reset false
+  app:
+    image: myapp
+    ports: !reset []
     environment:
       FOO: !reset null
-    ports: !reset []
 ```
 
-Result in a Compose application model equivalent to the YAML tree:
+Results in:
 
 ```yaml
 services:
-  foo:
-    image: foo
-    build: null
-    read_only: false
-    environment: {}
-    ports: []
+  app:
+    image: myapp
 ```
 
 ### Replace value
@@ -3015,25 +3009,36 @@ While `!reset` can be used to remove a declaration from a Compose file using an
 you to fully replace an attribute, bypassing the standard merge rules. A typical example is to fully replace a 
 resource definition, to rely on a distinct model but using the same name.
 
-Merging the following example YAML trees:
+A base `compose.yaml` file:
 
 ```yaml
-networks:
-  foo:
-    # this is production configuration
-    name: production-overlay-network
-    driver: overlay
-    driver-opts: (...)
+services:
+app:
+    image: myapp
+    ports:
+      - "8080:80"
 ```
 
+To remove the original port, but expose a new one, the following override file is used:
+
 ```yaml
-networks:
-  # this is development configuration
-  foo: !override {}
+services:
+  app:
+    ports: !override
+      - "8443:443" 
 ```
 
-Results in a Compose application model equivalent to the override YAML tree.
+This results in: 
+
+```yaml
+services:
+  app:
+    image: myapp
+    ports:
+      - "8443:443" 
+```
 
+If `!override` had not been used, both `8080:80` and `8443:443` would be exposed as per the [merging rules outlined above](#sequence). 
 # Include
 
 A Compose application can declare dependency on another Compose application. This is useful if: