[commit: ghc] master: users-guide: Add references to various issues in bugs section (aa61174)

[git at git.haskell.org]

Repository : ssh://git@git.haskell.org/ghc

On branch  : master
Link       : http://ghc.haskell.org/trac/ghc/changeset/aa611746aa860e1884c9ad623d6939791f2645ff/ghc

>---------------------------------------------------------------

commit aa611746aa860e1884c9ad623d6939791f2645ff
Author: Ben Gamari <bgamari.foss at gmail.com>
Date:   Tue Mar 29 10:58:04 2016 +0200

    users-guide: Add references to various issues in bugs section
    
    Test Plan: Read it
    
    Reviewers: austin
    
    Reviewed By: austin
    
    Subscribers: thomie
    
    Differential Revision: https://phabricator.haskell.org/D2052
    
    GHC Trac Issues: #7411, #11197, #11554, #11715


>---------------------------------------------------------------

aa611746aa860e1884c9ad623d6939791f2645ff
 docs/users_guide/bugs.rst | 37 +++++++++++++++++++++++++++++++++++++
 1 file changed, 37 insertions(+)

diff --git a/docs/users_guide/bugs.rst b/docs/users_guide/bugs.rst
index ff43009..c4ac9ce 100644
--- a/docs/users_guide/bugs.rst
+++ b/docs/users_guide/bugs.rst
@@ -449,6 +449,43 @@ Bugs in GHC
    libraries that come with GHC are probably built without this option,
    unless you built GHC yourself.
 
+-  The :ghc-flag:`state hack <-fstate-hack>` optimization can result in
+   non-obvious changes in evaluation ordering which may hide exceptions, even
+   with :ghc-flag:`-fpedantic-bottoms` (see, e.g., :ghc-ticket:`7411`). For
+   instance, ::
+
+     import Control.Exception
+     import Control.DeepSeq
+     main = do
+         evaluate (('a' : undefined) `deepseq` return () :: IO ())
+         putStrLn "Hello"
+
+   Compiling this program with ``-O`` results in ``Hello`` to be printed,
+   despite the fact that ``evaluate`` should have bottomed. Compiling
+   with ``-O -fno-state-hack`` results in the exception one would expect.
+
+-  Programs compiled with :ghc-flag:`-fdefer-type-errors` may fail a bit
+   more eagerly than one might expect. For instance, ::
+
+     {-# OPTIONS_GHC -fdefer-type-errors #-}
+     main = do
+       putStrLn "Hi there."
+       putStrLn True
+
+   Will emit no output, despite the fact that the ill-typed term appears
+   after the well-typed ``putStrLn "Hi there."``. See :ghc-ticket:`11197`.
+
+-  Despite appearances ``*`` and ``Constraint`` aren't really distinct kinds
+   in the compiler's internal representation and can be unified producing
+   unexpected results. See :ghc-ticket:`11715` for one example.
+
+-  :ghc-flag:`-XTypeInType` still has a few rough edges, especially where
+   it interacts with other advanced type-system features. For instance,
+   this definition causes the typechecker to loop (:ghc-ticket:`11559`), ::
+
+     data A :: Type where
+       B :: forall (a :: A). A
+
 -  There is known to be maleficent interactions between weak references and
    laziness. Particularly, it has been observed that placing a thunk containing
    a reference to a weak reference inside of another weak reference may cause