Merge pull request #11044 from haskell/mergify/bp/3.16/pr-11018

Backport #11018: add paragraph mentioning stackage

Author: mergify[bot]

doc/cabal-project-description-file.rst

@@ -85,6 +85,16 @@ architecture and version information from, which will force some
 commands (update, sdist) to require ghc present where otherwise it
 would not be necessitated.
 
+One use case for imports is to specify a `Stackage <https://www.stackage.org/>`
+snapshot, so that your cabal project can use the same set of packages as
+that snapshot. To use the ``lts-21.25`` resolver, you can write
+``import: https://www.stackage.org/lts-21.25/cabal.config`` in your
+``cabal.project``.
+
+There are a number of limitations that come with this approach however; please
+see :ref:`How can I have a reproducible set of versions for my dependencies?<how reproducible>` for
+more information.
+
 Specifying the local packages
 -----------------------------
 

doc/nix-local-build.rst

@@ -104,6 +104,8 @@ for each package using :cfg-field:`profiling-detail`::
 Alternately, you can call ``cabal build --enable-profiling`` to
 temporarily build with profiling.
 
+.. _how reproducible:
+
 How can I have a reproducible set of versions for my dependencies?
 ------------------------------------------------------------------
 
@@ -134,6 +136,16 @@ development environments.
 .. _Stackage: https://stackage.org/
 .. _versions of packages in lts-19.2: https://www.stackage.org/lts-19.2
 
+Limitations
+^^^^^^^^^^^
+
+Stackage does not guarantee that the config files will work with revisions, and
+it's not currently possible to `override used versions of packages <https://github.com/haskell/cabal/issues/9511>`
+or to `specify revisions <https://github.com/haskell/cabal/issues/7833>` using
+cabal.
+
+To mitigate these shortcomings, download the linked ``cabal.config`` file, import this locally with a relative path and repeatedly ``cabal build all --dry-run`` to identify and then comment out version constraint conflicts until the cabal solver is happy.
+
 How it works
 ============