Clean up 8.0.2 release notes

1 files changed, 73 insertions, 8 deletions

diff --git a/docs/users_guide/8.0.2-notes.rst b/docs/users_guide/8.0.2-notes.rst
index 727e9198c9..81f9ce4f2d 100644
--- a/docs/users_guide/8.0.2-notes.rst
+++ b/docs/users_guide/8.0.2-notes.rst
@@ -3,24 +3,49 @@
 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
 ----------
 
+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
 ------------
 
 Language
 ~~~~~~~~
 
--  TODO FIXME.
-
 -  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`).
@@ -49,15 +74,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`).
 
 -  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
@@ -65,6 +106,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
 ~~~~~~~~~~~~~~
 
@@ -75,11 +126,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`).
 
+- 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