From 9a0505f28f0c4981ee70ba1e683785565e5c6980 Mon Sep 17 00:00:00 2001
From: Phil de Joux <philderbeast@gmail.com>
Date: Mon, 30 Oct 2023 13:52:41 -0400
Subject: [PATCH] Say something about hackage deprecations

---
 doc/cabal-package-description-file.rst | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/doc/cabal-package-description-file.rst b/doc/cabal-package-description-file.rst
index 1628df418fd..25bd520e9cc 100644
--- a/doc/cabal-package-description-file.rst
+++ b/doc/cabal-package-description-file.rst
@@ -1493,6 +1493,13 @@ system-dependent values for these fields.
        ``base-4.13`` and with later GHC versions, then we can use ``time >=1.12
        && (time <1.12.3 || time >1.12.3)``.
 
+       Hackage shows deprecated and preferred versions for packages, such as for
+       `containers <https://hackage.haskell.org/package/containers/preferred>`_
+       and `aeson <https://hackage.haskell.org/package/aeson/preferred>`_ for
+       example. Deprecating package versions is not the same deprecating a
+       package as a whole, for which hackage keeps a `deprecated packages list
+       <https://hackage.haskell.org/packages/deprecated>`_.
+
     If no version constraint is specified, any version is assumed to be
     acceptable. For example: