diff --git a/doc/cabal-package.rst b/doc/cabal-package.rst
index a5af5ad34166d8b4fce85d0e881153e9eaee44d1..c25290419bc7582c1640130b9cabe10e3bd551f7 100644
--- a/doc/cabal-package.rst
+++ b/doc/cabal-package.rst
@@ -763,7 +763,8 @@ describe the package as a whole:
     behaviour, put the files that wildcards will match against in
     their own folder.
 
-    ``**`` wildcards are available starting in Cabal 2.4.
+    ``**`` wildcards are available starting in Cabal 2.4
+    and `bug-free since Cabal 3.0 <https://github.com/haskell/cabal/issues/6125#issuecomment-1379878419>`_.
 
 .. pkg-field:: data-dir: directory
 
diff --git a/doc/file-format-changelog.rst b/doc/file-format-changelog.rst
index 300bdb21d3c91363b2556a5d87e651b603e7f04e..4aba3ce6dcdd23e7480acae3c33672c5f6a319bc 100644
--- a/doc/file-format-changelog.rst
+++ b/doc/file-format-changelog.rst
@@ -161,6 +161,10 @@ relative to the respective preceding *published* version.
     ``foo/**/bar.html`` are all invalid). As ``**`` was an error in
     globs before, this does not affect any existing ``.cabal`` files
     that previously worked.
+    (Caveat: Double-star wildcards in :pkg-field:`data-files` directories,
+    e.g. ``data-files: data/**/*.csv``,
+    `are only supported correctly from Cabal 3.0 <https://github.com/haskell/cabal/issues/6125#issuecomment-1379878419>`_.)
+
 
   * Wildcards now match when the pattern's extensions form a suffix of
     the candidate file's extension, rather than requiring strict