clarification on extends and include usage (#19318)

* clarification on extends and include usage

Signed-off-by: Nicolas De Loof <nicolas.deloof@gmail.com>

* Apply suggestions from code review

---------

Signed-off-by: Nicolas De Loof <nicolas.deloof@gmail.com>
Co-authored-by: Allie Sadler <102604716+aevesdocker@users.noreply.github.com>

content/compose/multiple-compose-files/extends.md

@@ -192,6 +192,40 @@ configuration. But this isn’t an acceptable solution when you want to re-use
 someone else's unfamiliar configurations and you don’t know about its own
 dependencies.
 
+## Relative paths
+
+When using `extends` with a `file` attribute which points to another folder, relative paths 
+declared by the service being extended are converted so they still point to the
+same file when used by the extending service. This is illustrated in the following example:
+
+Base Compose file:
+```yaml
+services:
+  webapp:
+    image: example
+    extends:
+      file: ../commons/compose.yaml
+      service: base
+```
+
+The `commons/compose.yaml` file:
+```yaml
+services:
+  base:
+    env_file: ./container.env
+```
+
+The resulting service refers to the original `container.env` file
+within the `commons` directory. This can be confirmed with `docker compose config`
+which inspects the actual model:
+```yaml
+services:
+  webapp:
+    image: example
+    env_file: 
+      - ../commons/container.env
+```
+
 ## Reference information
 
 - [`extends`](../compose-file/05-services.md#extends)

content/compose/multiple-compose-files/include.md

@@ -36,6 +36,47 @@ services:
 
 This means the team managing `serviceB` can refactor its own database component to introduce additional services without impacting any dependent teams. It also means that the dependent teams don't need to include additional flags on each Compose command they run.
 
+## Include and overrides
+
+Compose reports an error if any resource from `include` conflicts with resources from the included Compose file. This rule prevents
+unexpected conflicts with resources defined by the included compose file author. However, there may be some circumstances where you might want to tweak the
+included model. This can be achieved by adding an override file to the include directive:
+```yaml
+include:
+  - path : 
+      - third-party/compose.yaml
+      - override.yaml  # local override for third-party model
+```
+
+The main limitation with this approach is that you need to maintain a dedicated override file per include. For complex projects with multiple
+includes this would result into many Compose files.
+
+The other option is to use a `compose.override.yaml` file. While conflicts will be rejected from the file using `include` when same
+resource is declared, a global Compose override file can override the resulting merged model, as demonstrated in following example:
+
+Main `compose.yaml` file:
+```yaml
+include:
+  - team-1/compose.yaml # declare service-1
+  - team-2/compose.yaml # declare service-2
+```
+
+Override `compose.override.yaml` file:
+```yaml
+services:
+  service-1:
+    # override included service-1 to enable debugger port
+    ports:
+      - 2345:2345
+
+  service-2:
+    # override included service-2 to use local data folder containing test data
+    volumes:
+      - ./data:/data
+```
+
+Combined together, this allows you to benefit from third-party reusable components, and adjust the Compose model for your needs.
+
 ## Reference information
 
 [`include` top-level element](../compose-file/14-include.md)