From f2015738205f5cbaa99bc3aaf7297bb324f80f71 Mon Sep 17 00:00:00 2001
From: Javier Sagredo <jasataco@gmail.com>
Date: Tue, 21 Nov 2023 15:05:32 +0100
Subject: [PATCH] Document default-package-bounds

---
 changelog.d/package-constraints        | 12 ++++++
 doc/cabal-package-description-file.rst | 54 +++++++++++++++++++++++---
 doc/file-format-changelog.rst          |  7 ++++
 3 files changed, 67 insertions(+), 6 deletions(-)
 create mode 100644 changelog.d/package-constraints

diff --git a/changelog.d/package-constraints b/changelog.d/package-constraints
new file mode 100644
index 00000000000..5c30780ca58
--- /dev/null
+++ b/changelog.d/package-constraints
@@ -0,0 +1,12 @@
+synopsis: Implement `default-package-bounds` field
+packages: Cabal-syntax
+prs: #9462
+
+description: {
+
+The new `default-package-bounds` stanza can be used to default versions that are
+ommitted in the build-depends fields. This could be done previously by means of
+common stanzas but it was too verbose and obscure (dependencies came sometimes
+from stanzas).
+
+}
diff --git a/doc/cabal-package-description-file.rst b/doc/cabal-package-description-file.rst
index 8e5e59db1cf..d33fd1f4a10 100644
--- a/doc/cabal-package-description-file.rst
+++ b/doc/cabal-package-description-file.rst
@@ -790,6 +790,49 @@ describe the package as a whole:
     additional hooks, such as the scheme described in the section on
     `system-dependent parameters`_.
 
+.. pkg-field:: default-package-bounds: library list
+   :since: 3.12
+
+   Starting with **Cabal 3.12**, a new section ``default-package-bounds`` can be
+   declared on the package description which will provide version bounds that
+   will be used when a `build-depends` dependency doesn't specify a version
+   bound.
+
+   So the package description:
+
+   ::
+
+        package-constraints:
+          , x ^>= 5
+
+        library a
+          build-depends: x
+
+        library b
+          build-depends: x >5.5
+
+        library c
+          build-depends: y
+
+   will be equivalent to:
+
+   ::
+
+        library a
+          build-depends: x ^>=5
+
+        library b
+          build-depends: x >5.5
+
+        library c
+          build-depends: y
+
+   This process is only applied as a syntactic desugar, only to avoid
+   duplication and verbosity on the cabal file. It will not apply version bounds
+   on transitive dependencies that are not explicitly listed as a dependency. It
+   will not be applied to ``build-tool-depends`` or ``pkgconfig-depends``
+   entries.
+
 Library
 ^^^^^^^
 
@@ -1519,12 +1562,12 @@ system-dependent values for these fields.
     common because it is recommended practice for package versions to
     correspond to API versions (see PVP_).
 
-    Since Cabal 1.6, there is a special wildcard syntax to help with
+    Since **Cabal 1.6**, there is a special wildcard syntax to help with
     such ranges
 
     ::
 
-        build-depends: foo ==1.2.*
+        build-depends: foo ==1.2.***
 
     It is only syntactic sugar. It is exactly equivalent to
     ``foo >= 1.2 && < 1.3``.
@@ -1537,7 +1580,7 @@ system-dependent values for these fields.
        than ``1.0``. This is not an issue with the caret-operator
        ``^>=`` described below.
 
-    Starting with Cabal 2.0, there's a new version operator to express
+    Starting with **Cabal 2.0**, there's a new version operator to express
     PVP_-style major upper bounds conveniently, and is inspired by similar
     syntactic sugar found in other language ecosystems where it's often
     called the "Caret" operator:
@@ -1628,8 +1671,8 @@ system-dependent values for these fields.
        renaming in ``build-depends``; however, this support has since been
        removed and should not be used.
 
-    Starting with Cabal 3.0, a set notation for the ``==`` and ``^>=`` operator
-    is available. For instance,
+    Starting with **Cabal 3.0**, a set notation for the ``==`` and ``^>=``
+    operator is available. For instance,
 
     ::
 
@@ -1646,7 +1689,6 @@ system-dependent values for these fields.
 
         build-depends: network ^>= { 2.6.3.6, 2.7.0.2, 2.8.0.0, 3.0.1.0 }
 
-
 .. pkg-field:: other-modules: identifier list
 
     A list of modules used by the component but not exposed to users.
diff --git a/doc/file-format-changelog.rst b/doc/file-format-changelog.rst
index c3d9aa2dfc8..66569b8b2a4 100644
--- a/doc/file-format-changelog.rst
+++ b/doc/file-format-changelog.rst
@@ -19,6 +19,13 @@ relative to the respective preceding *published* version.
     versions of the ``Cabal`` library denote unreleased development
     branches which have no stability guarantee.
 
+``cabal-version: 3.12``
+-----------------------
+
+* Added :pkg-field:`default-package-bounds` stanza. This allows to declare
+  constraints that will be used for the dependencies that have no specified
+  constraints associated in ``build-depends`` lists.
+
 ``cabal-version: 3.8``
 ----------------------