Give concrete example for #12784 in 8.0.2 release notes

Summary:
We mentioned that there were "some programs" that failed to typecheck
due to #12784, but given how surprisingly common this issue has been, it'd
be prudent to at least give one example of the bug in the release notes.

Reviewers: simonpj, bgamari, austin, rwbarton

Reviewed By: rwbarton

Subscribers: thomie

Differential Revision: https://phabricator.haskell.org/D2786

GHC Trac Issues: #12784

1 files changed, 19 insertions, 2 deletions

diff --git a/docs/users_guide/8.0.2-notes.rst b/docs/users_guide/8.0.2-notes.rst
index fa7aa8db3d..237c3b95ef 100644
--- a/docs/users_guide/8.0.2-notes.rst
+++ b/docs/users_guide/8.0.2-notes.rst
@@ -68,8 +68,25 @@ Language
         foo :: m ()
 
 -  Some programs using :ghc-flag:`-XDefaultSignatures` that incorrectly
-   type-checked in GHC 8.0.1 are now rejected by GHC 8.0.2. See
-   :ghc-ticket:`12784` for details.
+   type-checked in GHC 8.0.1 are now rejected by GHC 8.0.2. Here is a
+   characteristic example: ::
+
+      class Monad m => MonadSupply m where
+        fresh :: m Integer
+        default fresh :: (MonadTrans t, MonadSupply m) => t m Integer
+        fresh = lift fresh
+
+      instance MonadSupply m => MonadSupply (IdentityT m)
+
+   Note that the ``m`` in the default type signature is being used in
+   a completely different way than the ``m`` in the non-default signature!
+   We can fix this (in a backwards-compatible way) like so: ::
+
+      class Monad m => MonadSupply m where
+        fresh :: m Integer
+        default fresh :: (MonadTrans t, MonadSupply m', m ~ t m') => m Integer
+                         -- Same 'm Integer' after the '=>'
+        fresh = lift fresh
 
 -  Some programs which combine default type class method implementations and
    overlapping instances may now fail to type-check. Here is an example: ::