Document default-package-bounds

changelog.d/default-package-bounds

@@ -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).
+
+}

doc/cabal-package-description-file.rst

@@ -1528,12 +1528,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``.
@@ -1546,7 +1546,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:
@@ -1637,8 +1637,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,
 
     ::
 
@@ -1655,7 +1655,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.
@@ -2687,6 +2686,94 @@ Starting with Cabal-2.2 it's possible to use common build info stanzas.
 
     TBW
 
+.. _default-package-bounds:
+
+Default package bounds
+^^^^^^^^^^^^^^^^^^^^^^
+
+.. pkg-section:: default-package-bounds
+   :since: 3.14
+
+Starting with **Cabal 3.14**, a new section ``default-package-bounds`` can be
+declared on the package description to provide version bounds that will be used
+when there is no explicit bound on an entry on:
+
+- :pkg-field:`build-depends<None:build-depends>`
+- :pkg-field:`build-tool-depends<None:build-depends>`
+
+So the package description:
+
+::
+
+    default-package-bounds
+        build-depends:
+          , awesome-package ^>= 5
+        build-tool-depends:
+          , markdown-unlit:markdown-unlit < 100
+
+    custom-setup
+      setup-depends:
+        awesome-package
+
+    library a
+        build-depends:
+          , awesome-package
+        build-tool-depends:
+          , markdown-unlit:markdown-unlit
+
+    library b
+        build-depends:
+          , awesome-package >5.5
+        build-tool-depends:
+          , markdown-unlit:markdown-unlit >1
+
+    library c
+        build-depends: y
+
+will be equivalent to:
+
+::
+
+    custom-setup
+      setup-depends:
+        awesome-package
+
+    library a
+        build-depends:
+          , awesome-package ^>= 5
+        build-tool-depends:
+          , markdown-unlit:markdown-unlit < 100
+
+    library b
+        build-depends:
+          , awesome-package >5.5
+        build-tool-depends:
+          , markdown-unlit:markdown-unlit >1
+
+    library c
+        build-depends: y
+
+Notice only ``library a`` had its bounds modified. This process is only applied
+as a syntactic desugaring, only to avoid duplication and verbosity on the cabal
+file. More concretely,
+
+- it will **not** apply version bounds on transitive dependencies that are not explicitly listed as a dependency,
+- it will **not** add the listed dependencies to any component in which they were not already listed,
+- it will **not** modify bounds on :pkg-field:`pkgconfig-depends` entries.
+- it will **not** modify bounds on :pkg-field:`custom-setup:setup-depends` entries.
+
+Using ``--allow-newer`` or ``--allow-older`` will relax the ``default-package-bounds`` constraints
+in the same way as is done for normal :pkg-field:`build-depends<None:build-depends>` dependencies.
+
+.. pkg-field:: build-depends: library list
+
+    The bounds declared here will be applied to entries without explicit bounds in every
+    :pkg-field:`build-depends<None:build-depends>`.
+
+.. pkg-field:: build-tool-depends: package:executable list
+
+    The bounds declared here will be applied to entries without explicit bounds in every
+    :pkg-field:`build-tool-depends<None:build-tool-depends>`.
 
 .. _pkg-author-source:
 

doc/file-format-changelog.rst

@@ -19,13 +19,19 @@ relative to the respective preceding *published* version.
     versions of the ``Cabal`` library denote unreleased development
     branches which have no stability guarantee.
 
+``cabal-version: 3.14``
+-----------------------
+
+* Added :pkg-section:`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.12``
 -----------------------
 
 * License fields use identifiers from SPDX License List version
   ``3.23 2024-02-08``.
 
-
 ``cabal-version: 3.8``
 ----------------------