From 243c337f2f821300a7ff651556253ae776b832b0 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 | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/content/engine/release-notes/25.0.md b/content/engine/release-notes/25.0.md
index fcc2b4080f..8e7b8a05bc 100644
--- a/content/engine/release-notes/25.0.md
+++ b/content/engine/release-notes/25.0.md
@@ -28,6 +28,24 @@ 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, read-only bind mounts are **recursively read-only** by default.
+>
+> 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)