Document default-constraints

doc/cabal-package-description-file.rst

@@ -795,6 +795,49 @@ describe the package as a whole:
     additional hooks, such as the scheme described in the section on
     `system-dependent parameters`_.
 
+.. pkg-field:: default-constraints: library list
+   :since: 3.11
+
+   Starting with **Cabal 3.11**, a new section ``default-constraints`` can be
+   declared on the package description which will provide version bounds to the
+   dependencies that appear in ``build-depends`` lists with empty ranges.
+
+   So the package description:
+
+   ::
+
+        default-constraints:
+          , x ^>= 5
+
+        library a
+          build-depends: x
+
+        library b
+          build-depends: x >5.5
+
+        library c
+          build-depends: y
+
+   will be parsed as:
+
+   ::
+
+        library a
+          build-depends: x ^>=5
+
+        library b
+          build-depends: x >5.5
+
+        library c
+          build-depends: y
+
+   Notice that only unversioned bounds inherit the default-constraint clause.
+   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
 ^^^^^^^
 
@@ -1515,12 +1558,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``.
@@ -1533,7 +1576,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:
@@ -1545,7 +1588,7 @@ system-dependent values for these fields.
           bar ^>= 1
 
     This allows to assert the positive knowledge that this package is
-    *known* to be semantically compatible with the releases
+    **known* to be semantically compatible with the releases
     ``foo-1.2.3.4`` and ``bar-1`` respectively. The information
     encoded via such ``^>=``-assertions is used by the cabal solver to
     infer version constraints describing semantically compatible
@@ -1624,8 +1667,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,
 
     ::
 
@@ -1642,7 +1685,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.