Add a section about failable patterns in the GHC user's guide

1 files changed, 31 insertions, 0 deletions

diff --git a/docs/users_guide/bugs.rst b/docs/users_guide/bugs.rst
index d6e1970fea..cfcfc0417c 100644
--- a/docs/users_guide/bugs.rst
+++ b/docs/users_guide/bugs.rst
@@ -170,6 +170,37 @@ This improves efficiency slightly but significantly for most programs,
 and is bad for only a few. To suppress this bogus "optimisation" use
 ``-fpedantic-bottoms``.
 
+.. _infelicities-failable-pats:
+
+Failable patterns
+^^^^^^^^^^^^^^^^^
+
+Since the `MonadFail Proposal (MFP) <https://gitlab.haskell.org/haskell/prime/-/wikis/libraries/proposals/monad-fail>`__,
+do-notation blocks that contain a failable pattern need a `MonadFail <https://hackage.haskell.org/package/base-4.14.1.0/docs/Control-Monad-Fail.html#t:MonadFail>`__ constraint.
+
+For example
+
+::
+
+    mayFail :: (MonadIO m) => m ()
+    mayFail = do
+      (Just value) <- fetchData
+      putStrLn value
+
+Will warn you with
+
+::
+
+    • Could not deduce (MonadFail m)
+        arising from a do statement
+        with the failable pattern ‘(Just x)’
+      from the context: MonadIO m
+        bound by the type signature for:
+                   mayFail :: forall (m :: * -> *). MonadIO m => m ()
+
+And indeed, since the `Monad <https://hackage.haskell.org/package/base-4.14.1.0/docs/Control-Monad.html#t:Monad>`__ class does not have the ``fail`` method anymore,
+we need to explicitly add ``(MonadFail m)`` to the contraints of the function.
+
 .. _infelicities-decls:
 
 Declarations and bindings