From 9d0fe6af35d652b418927c79b8f6815e2663b737 Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Mon, 22 Jan 2024 15:04:18 +0100
Subject: [PATCH] engine: clarify breaking change for recursive mounts

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
---
 content/engine/release-notes/25.0.md | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/content/engine/release-notes/25.0.md b/content/engine/release-notes/25.0.md
index fcc2b4080f40..9030f986053e 100644
--- a/content/engine/release-notes/25.0.md
+++ b/content/engine/release-notes/25.0.md
@@ -28,6 +28,25 @@ For a full list of pull requests and changes in this release, refer to the relev
 - [docker/cli, 25.0.0 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A25.0.0)
 - [moby/moby, 25.0.0 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A25.0.0)
 
+> **Note**
+>
+> In earlier versions of Docker Engine, recursive mounts (submounts) would
+> always be mounted as writable, even when specifying a read-only mount. This
+> behavior has changed in v25.0.0, for hosts running on kernel version 5.12 or
+> later. Now, any submounts are recursively read-only by default for read-only
+> bind mounts.
+>
+> To get the same behavior as earlier releases, you can specify the
+> `bind-recursive` option for the `--mount` flag.
+>
+> ```console
+> $ docker run --mount type=bind,src=SRC,dst=DST,readonly,bind-recursive=writable IMAGE
+> ```
+>
+> This option isn't supported with the `-v` or `--volume` flag.
+> For more information, see
+> [Recursive mounts](../../storage/bind-mounts.md#recursive-mounts).
+
 ### New
 
 - Add OpenTelemetry tracing. [moby/moby#45652](https://github.com/moby/moby/pull/45652), [moby/moby#45579](https://github.com/moby/moby/pull/45579)