users_guide: Bring 8.0.2 release notes up-to-date with ghc-8.0 branch

I've been editing the release notes on the `ghc-8.0` branch; fold those
changes into `master`.

1 files changed, 83 insertions, 49 deletions

diff --git a/docs/users_guide/8.0.2-notes.rst b/docs/users_guide/8.0.2-notes.rst
index b28b92355f..063d94713d 100644
--- a/docs/users_guide/8.0.2-notes.rst
+++ b/docs/users_guide/8.0.2-notes.rst
@@ -3,12 +3,42 @@
 Release notes for version 8.0.2
 ===============================
 
-TODO FIXME
+The significant changes to the various parts of the compiler are listed in the
+following sections. There have also been numerous bug fixes and performance
+improvements over the 8.0.1 release.
+
+.. warning::
+
+    Only Cabal versions 1.24 and newer will function properly with this release.
+    (see :ghc-ticket:`11558`). Consequently it will likely be necessary to
+    recompile ``cabal-install`` before installing new packages.
+
+    The reason for this is a change in how packages are identified in GHC
+    8.0. While previous versions of Cabal identified packages to GHC with a
+    package key (with GHC's :ghc-flag:`-this-package-key` argument), GHC 8.0 and
+    later uses installed package IDs in place of package keys.
+
+.. note::
+
+    Users compiling GHC on Mac OS X with XCode 7.3 will need to tell the build
+    system to use the ``nm-classic`` command instead of Apple's new ``nm``
+    implementation as the latter breaks POSIX compliance (see
+    :ghc-ticket:`11744`). This can be done by passing something like
+    ``--with-nm=$(xcrun --find nm-classic)`` to ``configure``.
 
 Highlights
 ----------
 
-TODO FIXME.
+The highlights, since the 8.0.1 release, are:
+
+-  Compatibility fixes with macOS Sierra and recent Linux distributions.
+
+-  Many, many bug fixes.
+
+-  A bug has been fixed that caused standalone derived ``Ix`` instances to fail
+   for GADTs with exactly one constructor (:ghc-ticket:`12583`).
+
+-  Interface files produced by GHC should now be deterministic.
 
 Full details
 ------------
@@ -16,15 +46,6 @@ Full details
 Language
 ~~~~~~~~
 
--  TODO FIXME.
-
--  :ghc-flag:`-XStaticPointers` now allows the body of the ``static`` form to
-   refer to closed local bindings. For instance, this is now permitted:
-   ``f = static x where x = 'a'``.
-
--  A bug has been fixed that caused standalone derived ``Ix`` instances to fail
-   for GADTs with exactly one constructor (:ghc-ticket:`12583`).
-
 -  A bug has been fixed that caused derived ``Show`` instances to fail in the
    presence of :ghc-flag:`-XRebindableSyntax` and
    :ghc-flag:`-XOverloadedStrings` (:ghc-ticket:`12688`).
@@ -68,17 +89,31 @@ Language
 Compiler
 ~~~~~~~~
 
+-  A compiler bug present in 8.0.1 resulting in undefined reference errors while
+   compiling some packages has been fixed. (see :ghc-ticket:`12076`).
+
+-  A code generator bug which resulted in segmentation faults in compiled
+   programs has been fixed (see :ghc-ticket:`12757`).
+
+-  GHC now supports systems whose C compiler which produce position-independent
+   executables by default. (see :ghc-ticket:`12579`).
+
+-  GHC can now be built on systems which use the ``gold`` linker by default
+   (see :ghc-ticket:`12816`).
+
+-  GHC now reliably runs on macOS Sierra systems. Sierra introduced a linker
+   limitation which GHC occassionally surpassed when compiling programs with
+   many package dependencies. (see :ghc-ticket:`12479`).
+
 -  The :ghc-flag:`-Wredundant-constraints` flag has been removed from the
    :ghc-flag:`-Wall` flag set (see :ghc-ticket:`10635`).
 
--  The :ghc-flag:`-ddump-cmm` now dumps the result after C-- pipeline pass. Two
-   more flags were added: :ghc-flag:`-ddump-cmm-from-stg` to allow to get the
-   initial cmm from STG-to-C-- code generation and :ghc-flag:`-ddump-cmm-verbose`
-   to obtain the intermediates from all C-- pipeline stages.
+-  Added :ghc-flag:`-fdefer-out-of-scope-variables`, which converts variable
+   out of scope variables errors into warnings.
 
--  The RTS :ghc-flag: `-xb` now reads the base heap address in any base,
-   defaulting to decimal, hexadecimal if the address starts with `0x`, and
-   octal if the address starts with `0`.
+-  The RTS :ghc-flag:`-xb` now reads the base heap address in any base,
+   defaulting to decimal, hexadecimal if the address starts with ``0x``, and
+   octal if the address starts with ``0``.
 
 -  Due to an oversight in GHC 8.0.1, the value of the preprocessor macro
    ``__GLASGOW_HASKELL_LLVM__``, which exposes the LLVM version used by GHC, was
@@ -86,6 +121,16 @@ Compiler
    formatting is changed to be in line with ``__GLASGOW_HASKELL__``
    (:ghc-ticket:`12628`).
 
+-  Parallel programs should be significantly more reliable on platforms with weak
+   memory consistency guarantees (:ghc-ticket:`12469`)
+
+-  Interface files should now be bit-wise identical for a given build.
+   (:ghc-ticket:`4012`)
+
+- Nearly two-hundred more bugs. See `Trac
+   <https://ghc.haskell.org/trac/ghc/query?status=closed&milestone=8.0.2&col=id&col=summary&col=status&col=type&col=priority&col=milestone&col=component&order=priority>`_
+   for a complete list.
+
 Runtime system
 ~~~~~~~~~~~~~~
 
@@ -96,14 +141,25 @@ Runtime system
   `MSDN <https://msdn.microsoft.com/en-us/library/ms235384.aspx>`_ . This should now introduce the same behavior
   both compiled and interpreted. (see :ghc-ticket:`12497`).
 
--  Added :ghc-flag:`-fdefer-out-of-scope-variables`, which converts variable
-   out of scope variables errors into warnings.
+- Profiles from the cost-center profiler now provide source span information.
+  (see :ghc-ticket:`11543`).
+
+- The number of threads used for garbage collection is now configurable
+  independently from the number of capabilities with the new :ghc-flag:`-qn`
+  flag.
+
+- The runtime system should now wake-up less often with large capability counts
+
+- The runtime system is now a more efficient in handling programs with many
+  bound threads. (:ghc-ticket:`12419`)
+
+- A number of runtime system bugs which could result in crashes (see
+  :ghc-ticket:`12728`, :ghc-ticket:`10860`, :ghc-ticket:`12019`,
+  :ghc-ticket:`11978`,  :ghc-ticket:`12038`, :ghc-ticket:`12208`)
 
 Template Haskell
 ~~~~~~~~~~~~~~~~
 
--  TODO FIXME.
-
 - ``addModFinalizer`` now exposes the local typing environment at the splice
   point. This allows ``reify`` to see local and top-level definitions in the
   current declaration group when used as in
@@ -112,32 +168,10 @@ Template Haskell
 
       f x = $(addModFinalizer (reify 'x >>= runIO . print) >> [| x |])
 
-TODO FIXME Heading title
-~~~~~~~~~~~~~~~~~~~~~~~~
-
--  GHCi now supports two new commands. :ghci-cmd:`:type` ``+d`` performs
-   defaulting on the type before reporting it to the user, and
-   :ghci-cmd:`:type` ``+v`` refrains from instantiating any variables before
-   reporting, which is useful in concert with :ghc-flag:`-XTypeApplications`.
-
-   .. code-block:: none
-
-	*X> :type +d length
-	length :: [a] -> Int
-
-	*X> :set -fprint-explicit-foralls
-	*X> :type length
-	length :: forall {a} {t :: * -> *}. Foldable t => t a -> Int
-	*X> :type +v length
-	length :: forall (t :: * -> *). Foldable t => forall a. t a -> Int
-
-Libraries
----------
+``ghc`` library
+~~~~~~~~~~~~~~~
 
-ghc
-~~~
+- Accessors are now exposed for ``ErrUtils.ErrMsg`` and ``ErrUtils.ErrDoc``.
 
--  The ``GHC.initGhcMonad`` function no longer installs signal handlers by
-   default. This means that the RTS won't attempt to handle Ctrl-C gracefully.
-   If you would like to use GHC's signal handlers, call
-   ``GHC.installSignalHandlers`` during initialization.
+- There is now a ``createIservProcessHook`` to allow API users to redirect the
+  ``stdout`` and ``stderr`` handles.