docs: add skeleton 8.2.1 release notes
authorAustin Seipp <austin@well-typed.com>
Wed, 11 May 2016 13:52:08 +0000 (15:52 +0200)
committerBen Gamari <ben@smart-cactus.org>
Thu, 12 May 2016 13:37:41 +0000 (15:37 +0200)
Summary:
Out with the old, in with the new.

Not much has diverged yet, but it's good to get this out of the way early.

Signed-off-by: Austin Seipp <austin@well-typed.com>
Test Plan: Built and looked at the documentation.

Reviewers: bgamari

Reviewed By: bgamari

Subscribers: thomie

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

docs/users_guide/8.0.1-notes.rst [deleted file]
docs/users_guide/8.2.1-notes.rst [new file with mode: 0644]
docs/users_guide/index.rst

diff --git a/docs/users_guide/8.0.1-notes.rst b/docs/users_guide/8.0.1-notes.rst
deleted file mode 100644 (file)
index 5b10a32..0000000
+++ /dev/null
@@ -1,796 +0,0 @@
-.. _release-8-0-1:
-
-Release notes for version 8.0.1
-===============================
-
-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 7.10 branch.
-
-.. 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 7.10 branch, are:
-
-- TODO FIXME
-
-- The new :ghc-flag:`-XTypeInType` allows promotion of all types into
-  kinds, allowing kind synonyms, kind families, promoted GADTs, and other
-  goodies.
-
-- Support for :ref:`record pattern synonyms <record-patsyn>`
-
-- The :ghc-flag:`-XDeriveAnyClass` extension learned to derive instances for
-  classes with associated types (see :ref:`derive-any-class`)
-
-- More reliable DWARF debugging information
-
-- Support for :ref:`injective type families <injective-ty-fams>`
-
-- Applicative ``do`` notation (see :ref:`applicative-do`)
-
-- Support for wildcards in data and type family instances
-
-- :ghc-flag:`-XStrict` and :ghc-flag:`-XStrictData` extensions, allowing modules
-  to be compiled with strict-by-default bindings (see :ref:`strict-haskell`)
-
-- :ghc-flag:`-XDuplicateRecordFields`, allowing multiple datatypes to declare the same
-  record field names provided they are used unambiguously (see :ref:`duplicate-record-fields`)
-
-- Support for lightweight
-  :ref:`callstacks and source locations <hascallstack>`
-
-- User-defined error messages for type errors
-
-- A rewritten (and greatly improved) pattern exhaustiveness checker
-
-- More flexible rebindable syntax
-
-- GHC can run the interpreter in a separate process (see
-  :ref:`external-interpreter`), and the interpreter can now run profiled
-  code.
-
-- GHCi now provides access to stack traces when used with
-  :ghc-flag:`-fexternal-interpreter` and :ghc-flag:`-prof` (see
-  :ref:`ghci-stack-traces`).
-
-- A native code generator for powerpc64 and powerpc64le architectures
-
-- The reworked users guide you are now reading
-
-- Support for Windows XP and earlier has been dropped.
-
-- GHC RTS No longer re-exports POSIX functions under their deprecated
-  names on Windows.
-
-Full details
-------------
-
-Language
-~~~~~~~~
-
--  TODO FIXME.
-
--  :ghc-flag:`-XTypeInType` supports universal type promotion and merges
-   the type and kind language. This allows, for example, higher-rank
-   kinds, along with kind families and type-level GADTs. Support is still
-   experimental, and it is expected to improve over the next several
-   releases. See :ref:`type-in-type` for the details.
-
--  The parser now supports Haddock comments on GADT data constructors.
-   For example ::
-
-        data Expr a where
-            -- | Just a normal sum
-            Sum :: Int -> Int -> Expr Int
-
--  The new ``base`` constraint :base-ref:`GHC.Stack.HasCallStack <GHC-Stack.html>`
-   can be used by functions to request a partial call-stack. For example ::
-
-        errorWithCallStack :: HasCallStack => String -> a
-        errorWithCallStack msg = error (msg ++ "\n" ++ prettyCallStack callStack)
-
-        ghci> errorWithCallStack "die"
-        *** Exception: die
-        CallStack (from HasCallStack):
-          errorWithCallStack, called at <interactive>:2:1 in interactive:Ghci1
-
-   prints the call-site of ``errorWithCallStack``.
-
-   See :ref:`hascallstack` for a description of ``HasCallStack``.
-
--  GHC now supports visible type application, allowing
-   programmers to easily specify how type parameters should be
-   instantiated when calling a function. See
-   :ref:`visible-type-application` for the details.
-
--  To conform to the common case, the default role assigned to
-   parameters of datatypes declared in ``hs-boot`` files is
-   ``representational``. However, if the constructor(s) for the datatype
-   are given, it makes sense to do normal role inference. This is now
-   implemented, effectively making the default role for non-abstract
-   datatypes in ``hs-boot`` files to be ``phantom``, like it is in
-   regular Haskell code.
-
--  Wildcards can be used in the type arguments of type/data family
-   instance declarations to indicate that the name of a type variable
-   doesn't matter. They will be replaced with new unique type variables.
-   See :ref:`data-instance-declarations` for more details.
-
--  GHC now allows to declare type families as injective. Injectivity
-   information can then be used by the typechecker. See
-   :ref:`injective-ty-fams` for details.
-
--  Due to a :ghc-ticket:`security issue <10826>`, Safe Haskell now forbids
-   annotations in programs marked as :ghc-flag:`-XSafe`.
-
--  Generic instances can be derived for data types whose constructors have
-   arguments with certain unlifted types. See :ref:`generic-programming` for
-   more details.
-
--  GHC generics can now provide strictness information for fields in a data
-   constructor via the ``Selector`` type class.
-
--  The :ghc-flag:`-XDeriveAnyClass` extension now fills in associated type family
-   default instances when deriving a class that contains them.
-
--  The :ghc-flag:`-XRebindableSyntax` feature is now much more flexible, imposing
-   fewer restrictions on the types of the rebindable syntax elements. For example,
-   your ``negate`` function may now return a different type than it accepts.
-   Rebindable syntax also supports higher-rank types fully, allowing types
-   like ``(>>=) :: m a -> (forall x. a x -> m b) -> m b``.
-
--  Users can now define record pattern synonyms. This allows pattern synonyms
-   to behave more like normal data constructors. For example, ::
-
-      pattern P :: a -> b -> (a, b)
-      pattern P{x,y} = (x,y)
-
-   will allow ``P`` to be used like a record data constructor and also defines
-   selector functions ``x :: (a, b) -> a`` and ``y :: (a, b) -> b``.
-
--  Pattern synonyms can now be bundled with type constructors. For a pattern
-   synonym ``P`` and a type constructor ``T``, ``P`` can be bundled with ``T``
-   so that when ``T`` is imported ``P`` is also imported. With this change
-   a library author can provide either real data constructors or pattern
-   synonyms in an opaque manner. See :ref:`pattern-synonyms` for details. ::
-
-      -- Foo.hs
-      module Foo ( T(P) ) where
-
-      data T = T
-
-      pattern P = T
-
-      -- Baz.hs
-      module Baz where
-
-      -- P is imported
-      import Foo (T(..))
-
--  Whenever a data instance is exported, the corresponding data family
-   is exported, too. This allows one to write ::
-
-     -- Foo.hs
-     module Foo where
-
-     data family T a
-
-     -- Bar.hs
-     module Bar where
-
-     import Foo
-
-     data instance T Int = MkT
-
-     -- Baz.hs
-     module Baz where
-
-     import Bar (T(MkT))
-
-   In previous versions of GHC, this required a workaround via an
-   explicit export list in ``Bar``.
-
--  GHC has grown a :ghc-flag:`-XUndecidableSuperClasses` language extension,
-   which relaxes GHC's recursive superclass check (see :ghc-ticket:`11318`).
-   This allows class definitions which have mutually recursive superclass
-   constraints at the expense of potential non-termination in the solver.
-
--  The compiler is now a bit more conservative in solving constraints previously
-   provided by superclasses (see :ghc-ticket:`11762`). For instance, consider
-   this program,::
-
-     {-# LANGUAGE FlexibleInstances #-}
-     {-# LANGUAGE UndecidableInstances #-}
-
-     class Super a
-     class (Super a) => Left a
-     class (Super a) => Right a
-     instance (Left a) => Right a    -- this is now an error
-
-   GHC now rejects this instance, claiming it cannot deduce the ``Super a``
-   superclass constraint of the ``Right`` typeclass. This stands in contrast to
-   previous releases, which would accept this declaration, using the ``Super a``
-   constraint implied by the ``Left a`` constraint. To fix this simply add the
-   needed superclass constraint explicitly, ::
-
-     instance (Left a, Super a) => Right a
-
--  :ghc-flag:`-XDeriveFoldable` and :ghc-flag:`-XDeriveTraversable` now
-   generate code without superfluous ``mempty`` or ``pure`` expressions. As a
-   result, :ghc-flag:`-XDeriveTraversable` now works on datatypes that contain
-   arguments which have unlifted types.
-
--  Note that the :ghc-flag:`-XImpredicativeTypes` extension, which has been
-   :ghc-wiki:`known <ImpredicativePolymorphism>` to be broken for many years, is even more
-   broken than usual in this release (see :ghc-ticket:`11319`,
-   :ghc-ticket:`11675`, and others). During pre-release testing we encountered
-   a number of projects that broke with confusing type errors due to (often
-   unnecessary) use of :ghc-flag:`-XImpredicativeTypes`. Users of
-   :ghc-flag:`-XImpredicativeTypes` do so at their own risk!
-
-Compiler
-~~~~~~~~
-
--  The LLVM code generator now supports only LLVM 3.7. This is in contrast to our
-   previous policy where GHC would try to support a range of LLVM versions
-   concurrently. We hope that by supporting a narrower range of versions we can
-   provide more reliable support for each.
-
--  Warnings can now be controlled with ``-W(no-)...`` flags in addition to
-   the old ``-f(no-)warn...`` ones. This was done as the first part of a
-   rewrite of the warning system to provide better control over warnings,
-   better warning messages, and more common syntax compared to other
-   compilers. The old ``-f``-based warning flags will remain functional for
-   the forseeable future.
-
--  Added the option :ghc-flag:`-dth-dec-file`. This dumps out a ``.th.hs`` file of
-   all Template Haskell declarations in a corresponding .hs file. The
-   idea is that application developers can check this into their
-   repository so that they can grep for identifiers used elsewhere that
-   were defined in Template Haskell. This is similar to using
-   :ghc-flag:`-ddump-to-file` with :ghc-flag:`-ddump-splices` but it always generates a
-   file instead of being coupled to :ghc-flag:`-ddump-to-file` and only outputs
-   code that does not exist in the .hs file and a comment for the splice
-   location in the original file.
-
--  After a long hiatus (see :ghc-ticket:`10935`) the
-   :ghc-flag:`-Wmonomorphism-restriction` (formerly
-   :ghc-flag:`-fwarn-monomorphism-restriction`) flag has returned.
-   The functionality of this flag was inadvertently removed by a commit in 2010;
-   this has been fixed and the flag should now issue warnings as it
-   previously did.
-
--  Added the option :ghc-flag:`-fprint-expanded-types`. When enabled, GHC also
-   prints type-synonym-expanded types in type errors.
-
--  Added the option :ghc-flag:`-fcpr-anal`. When enabled, the demand analyser
-   performs CPR analysis. It is implied by :ghc-flag:`-O`. Consequently,
-   :ghc-flag:`-fcpr-off` is now removed, run with :ghc-flag:`-fno-cpr-anal` to get the
-   old :ghc-flag:`-fcpr-off` behaviour.
-
--  Added the option :ghc-flag:`-fworker-wrapper`. When enabled, the worker-wrapper
-   transformation is performed after a strictness analysis pass. It is implied
-   by :ghc-flag:`-O` and by :ghc-flag:`-fstrictness`. It is disabled by :ghc-flag:`-fno-strictness`.
-   Enabling :ghc-flag:`-fworker-wrapper` while strictness analysis is disabled (by
-   :ghc-flag:`-fno-strictness`) has no effect.
-
--  Added the options :ghc-flag:`-Wmissed-specialisations` and
-   :ghc-flag:`-Wall-missed-specialisations`. When enabled, the simplifier will
-   produce a warning when a overloaded imported function cannot be
-   specialised (typically due to a missing ``INLINEABLE`` pragma). This
-   is intended to alert users to cases where they apply ``INLINEABLE`` but
-   may not get the speed-up they expect.
-
--  Added the option :ghc-flag:`-Wnoncanonical-monad-instances` and
-   :ghc-flag:`-Wnoncanonical-monadfail-instances` which help detect noncanonical
-   ``Applicative``/``Monad``/``MonadFail`` instance definitions.
-   See flag description in :ref:`options-sanity` for more details.
-
--  When printing an out-of-scope error message, GHC will give helpful advice if
-   the error might be caused by too restrictive imports.
-
--  Added the :ghc-flag:`-Wcompat` warning group, along with its opposite
-   :ghc-flag:`-Wno-compat`. Turns on warnings that will be enabled by default in the
-   future, but remain off in normal compilations for the time being. This
-   allows library authors eager to make their code future compatible to adapt
-   to new features before they even generate warnings.
-
--  Added the :ghc-flag:`-Wmissing-monadfail-instances` flag. When enabled, this
-   will issue a warning if a failable pattern is used in a context that does
-   not have a ``MonadFail`` constraint. This flag represents phase 1 of the
-   `MonadFail Proposal (MFP)
-   <https://prime.haskell.org/wiki/Libraries/Proposals/MonadFail>`__.
-
--  Added the :ghc-flag:`-Wsemigroup` flag. When enabled, this
-   will issue a warning if a type is an instance of ``Monoid`` but not
-   ``Semigroup``, and when a custom definition ``(<>)`` is made. Fixing these
-   warnings makes sure the definition of ``Semigroup`` as a superclass of
-   ``Monoid`` does not break any code.
-
--  Added the :ghc-flag:`-Wmissing-pattern-synonym-signatures`
-   flag. When enabled, this will issue a warning when a pattern
-   synonym definition doesn't have a type signature.  It is turned off
-   by default but enabled by :ghc-flag:`-Wall`.
-
--  Added the :ghc-flag:`-Wunused-type-patterns` flag to report unused
-   type variables in data and type family instances. This flag is not implied
-   by :ghc-flag:`-Wall`, since :ghc-flag:`-Wunused-type-patterns` will
-   warn about unused type variables even if the types themselves are intended
-   to be used as documentation. If :ghc-flag:`-Wunused-type-patterns` is
-   enabled, one can prefix or replace unused type variables with underscores to
-   avoid warnings.
-
--  Split off the new flag :ghc-flag:`-Wunused-foralls` from the previously
-   existing flag :ghc-flag:`-Wunused-matches`. :ghc-flag:`-Wunused-foralls`
-   emits a warning in the specific case that a user writes explicit ``forall``
-   syntax with unused type variables, while :ghc-flag:`-Wunused-matches` only
-   warns in the case of unused term-level patterns. Both flags are implied by
-   :ghc-flag:`-W`.
-
--  Added the :ghc-flag:`-fmax-pmcheck-iterations` to control how many times
-   the pattern match checker iterates. Since coverage checking is exponential
-   in the general case, setting a default number of iterations prevents memory
-   and performance blowups. By default, the number of iterations is set to
-   2000000 but it can be set with: ``-fmax-pmcheck-iterations=<n>``.
-   If the set number of iterations is exceeded, an informative warning is
-   issued.
-
--  :ghc-flag:`-this-package-key` has been renamed again (hopefully for the last time!)
-   to :ghc-flag:`-this-unit-id`.  The renaming was motivated by the fact that
-   the identifier you pass to GHC here doesn't have much to do with packages:
-   you may provide different unit IDs for libraries which are in the same
-   package.  :ghc-flag:`-this-package-key` is deprecated; you should use
-   :ghc-flag:`-this-unit-id` or, if you need compatibility over multiple
-   versions of GHC, :ghc-flag:`-package-name`.
-
--  When :ghc-flag:`-fdefer-type-errors` is enabled and an expression fails to
-   typecheck, ``Control.Exception.TypeError`` will now be thrown instead of
-   ``Control.Exception.ErrorCall``.
-
--  :ghc-flag:`-Wmissing-local-sigs` is now deprecated in favor of
-   :ghc-flag:`-Wmissing-local-signatures`.
-
--  :ghc-flag:`-Wmissing-exported-sigs` is now deprecated in favor of
-   :ghc-flag:`-Wmissing-exported-signatures`.
-
--  :ghc-flag:`-ddump-strsigs` has been renamed to
-   :ghc-flag:`-ddump-str-signatures`.
-
--  :ghc-flag:`-XDeriveGeneric` is now less picky about instantiating type
-   arguments when deriving (:ghc-ticket:`11732`). As a consequence, the
-   following code is now legal (whereas before it would have been rejected). ::
-
-     data T a b = T a b
-     deriving instance Generic (T Int b)
-
-GHCi
-~~~~
-
--  ``Main`` with an explicit module header but without ``main`` is now
-   an error (:ghc-ticket:`7765`).
-
--  The :ghci-cmd:`:back` and :ghci-cmd:`:forward` commands now take an optional count
-   allowing the user to move forward or backward in history several
-   steps at a time.
-
--  Added commands :ghci-cmd:`:load! <:load>` and :ghci-cmd:`:reload! <:reload>`,
-   effectively setting :ghc-flag:`-fdefer-type-errors` before loading a module and
-   unsetting it after loading if it has not been set before (:ghc-ticket:`8353`).
-
--  ``ghci -e`` now behaves like :ghc-flag:`ghc -e <-e>` (:ghc-ticket:`9360`).
-
--  Added support for top-level function declarations (:ghc-ticket:`7253`).
-
--  The new commands :ghci-cmd:`:all-types`, :ghci-cmd:`:loc-at`, :ghci-cmd:`:type-at`, and
-   :ghci-cmd:`:uses` designed for editor-integration
-   (such as Emacs' ``haskell-mode``) originally premiered by ``ghci-ng``
-   have been integrated into GHCi (:ghc-ticket:`10874`).
-
--  GHCi now supports decoupled operation between the interpreter and the
-   shell. While this is largely an implementation detail, it opens up a few
-   interesting possibilities in the future. See :ghc-wiki:`RemoteGHCi` for
-   details.
-
-Template Haskell
-~~~~~~~~~~~~~~~~
-
--  The new :ghc-flag:`-XTemplateHaskellQuotes` flag allows to use the
-   quotes (not quasi-quotes) subset of ``TemplateHaskell``.  This is
-   particularly useful for use with a stage 1 compiler (i.e. GHC
-   without interpreter support). Also, :ghc-flag:`-XTemplateHaskellQuotes` is
-   considered safe under Safe Haskell.
-
--  The ``__GLASGOW_HASKELL_TH__`` CPP constant denoting support for
-   :ghc-flag:`-XTemplateHaskell` introduced in GHC 7.10.1 has been changed to
-   use the values ``1``/``0`` instead of the previous ``YES``/``NO``
-   values.
-
--  Partial type signatures can now be used in splices, see
-   :ref:`pts-where`.
-
--  Template Haskell now fully supports typed holes and quoting unbound
-   variables.  This means it is now possible to use pattern splices nested
-   inside quotation brackets.
-
--  Template Haskell now supports the use of ``UInfixT`` in types to
-   resolve infix operator fixities, in the same vein as ``UInfixP`` and
-   ``UInfixE`` in patterns and expressions. ``ParensT`` and ``InfixT``
-   have also been introduced, serving the same functions as their
-   pattern and expression counterparts.
-
-- Template Haskell has now explicit support for representing GADTs.  Until
-  now GADTs were encoded using ``NormalC``, ``RecC`` (record syntax) and
-  ``ForallC`` constructors.  Two new constructors - ``GadtC`` and ``RecGadtC`` -
-  are now supported during quoting, splicing and reification.
-
--  Primitive chars (e.g., ``[| 'a'# |]``) and primitive strings (e.g.,
-   ``[| "abc"# |]``) can now be quoted with Template Haskell. The
-   ``Lit`` data type also has a new constructor, ``CharPrimL``, for
-   primitive char literals.
-
--  ``addTopDecls`` now accepts annotation pragmas.
-
--  Internally, the implementation of quasi-quotes has been unified with
-   that of normal Template Haskell splices. Under the previous
-   implementation, top-level declaration quasi-quotes did not cause a
-   break in the declaration groups, unlike splices of the form
-   ``$(...)``. This behavior has been preserved under the new
-   implementation, and is now recognized and documented in
-   :ref:`th-syntax`.
-
--  The ``Lift`` class is now derivable via the :ghc-flag:`-XDeriveLift` extension. See
-   :ref:`deriving-lift` for more information.
-
--  The ``FamilyD`` data constructor and ``FamFlavour`` data type have
-   been removed. Data families are now represented by ``DataFamilyD`` and
-   open type families are now represented by ``OpenTypeFamilyD`` instead
-   of ``FamilyD``. Common elements of ``OpenTypeFamilyD`` and
-   ``ClosedTypeFamilyD`` have been moved to ``TypeFamilyHead``.
-
--  The representation of ``data``, ``newtype``, ``data instance``, and
-   ``newtype instance`` declarations has been changed to allow for
-   multi-parameter type classes in the ``deriving`` clause. In particular,
-   ``dataD`` and ``newtypeD`` now take a ``CxtQ`` instead of a ``[Name]``
-   for the list of derived classes.
-
--  ``isExtEnabled`` can now be used to determine whether a language extension
-   is enabled in the ``Q`` monad. Similarly, ``extsEnabled`` can be used to list
-   all enabled language extensions.
-
--  One can now reify the strictness information of a constructors' fields using
-   Template Haskell's ``reifyConStrictness`` function, which takes into account
-   whether flags such as :ghc-flag:`-XStrictData` or
-   :ghc-flag:`-funbox-strict-fields` are enabled.
-
--  Previously, quoting a type signature like ``a -> a`` would produce the
-   abstract syntax for ``forall a. a -> a``. This behavior remains, but it
-   is extended to kinds, too, meaning that ``Proxy a -> Proxy a`` becomes
-   ``forall k (a :: k). Proxy a -> Proxy a``. This change is not intentional,
-   but is forced by the fact that GHC has a hard time telling kinds apart
-   from types. The effect of this change is that round-tripping kind-
-   polymorphic types will now require :ghc-flag:`-XTypeInType`.
-
-Runtime system
-~~~~~~~~~~~~~~
-
-- We have a shiny new two-step memory allocator for 64-bit platforms (see
-  :ghc-ticket:`9706`). In addition to simplifying the runtime system's
-  implementation this may significantly improve garbage collector performance.
-  Note, however, that Haskell processes will have an apparent virtual memory
-  footprint of a terabyte or so. Don't worry though, most of this amount is merely
-  mapped but uncommitted address space which is not backed by physical memory.
-
-- Support for performance monitoring with PAPI has been dropped.
-
-- :rts-flag:`-maxN⟨x⟩ <-maxN>` flag added to complement :rts-flag:`-N`. It will
-  choose to use at most ⟨x⟩ capabilities, limited by the number of processors
-  as :rts-flag:`-N` is.
-
-- The runtime linker is no longer greedy and will load only the needed objects
-  from archives. This means particularly on Windows packages requiring e.g. C99
-  support will now function properly. As part of this the RTS on Windows
-  no longer re-exports deprecated posix functions under the undeprecated names
-  (see :ghc-ticket:`11223`).
-
-Build system
-~~~~~~~~~~~~
-
--  TODO FIXME.
-
-Package system
-~~~~~~~~~~~~~~
-
--  TODO FIXME.
-
-hsc2hs
-~~~~~~
-
-- :command:`hsc2hs` now supports the ``#alignment`` macro, which can be used to
-  calculate the alignment of a struct in bytes. Previously, ``#alignment``
-  had to be implemented manually via a ``#let`` directive, e.g., ::
-
-      #let alignment t = "%lu", (unsigned long)offsetof(struct {char x__; t (y__); }, y__)
-
-  As a result, if you have the above directive in your code, it will now emit
-  a warning when compiled with GHC 8.0.
-
-  .. code-block:: none
-
-      Module.hsc:24:0: warning: "hsc_alignment" redefined [enabled by default]
-      In file included from dist/build/Module_hsc_make.c:1:0:
-      /path/to/ghc/lib/template-hsc.h:88:0: note: this is the location of the previous definition
-       #define hsc_alignment(t...) \
-       ^
-
-  To make your code free of warnings on GHC 8.0 and still support earlier
-  versions, surround the directive with a pragma checking for the right GHC
-  version. ::
-
-      #if __GLASGOW_HASKELL__ < 800
-      #let alignment t = "%lu", (unsigned long)offsetof(struct {char x__; t (y__); }, y__)
-      #endif
-
-Libraries
----------
-
-array
-~~~~~
-
--  Version number XXXXX (was 0.5.0.0)
-
-
-.. _lib-base:
-
-base
-~~~~
-
-See ``changelog.md`` in the ``base`` package for full release notes.
-
--  Version number 4.9.0.0 (was 4.7.0.0)
-
--  :base-ref:`GHC.Stack <GHC-Stack.html>` exports two new types ``SrcLoc`` and ``CallStack``. A
-   ``SrcLoc`` contains package, module, and file names, as well as start
-   and end positions. A ``CallStack`` is essentially a ``[(String, SrcLoc)]``,
-   sorted by most-recent call.
-
--  ``error`` and ``undefined`` will now report a partial stack-trace
-   using the new ``CallStack`` feature (and the :ghc-flag:`-prof` stack if
-   available).
-
--  A new function, ``interruptible``, was added to ``GHC.IO`` allowing
-   an ``IO`` action to be run such that it can be interrupted by an
-   asynchronous exception, even if exceptions are masked (except if
-   masked with ``interruptibleMask``).
-
-   This was introduced to fix the behavior of ``allowInterrupt``, which
-   would previously incorrectly allow exceptions in uninterruptible
-   regions (see :ghc-ticket:`9516`).
-
--  Per-thread allocation counters (``setAllocationCounter`` and
-   ``getAllocationCounter``) and limits (``enableAllocationLimit``,
-   ``disableAllocationLimit`` are now available from ``System.Mem``. Previously
-   this functionality was only available from :base-ref:`GHC.Conc <GHC-Stack.html>`.
-
-- ``forever``, ``filterM``, ``mapAndUnzipM``, ``zipWithM``, ``zipWithM_``,
-  ``replicateM``, and ``replicateM`` were generalized from ``Monad`` to
-  ``Applicative``. If this causes performance regressions, try to make the
-  implementation of ``(*>)`` match that of ``(>>)``.
-
-- Add ``URec``, ``UAddr``, ``UChar``, ``UDouble``, ``UFloat``, ``UInt``, and ``UWord`` to
-  :base-ref:`GHC.Generics <GHC-Generics.html>` as part of making GHC generics
-  capable of handling unlifted types (:ghc-ticket:`10868`)
-
-- Expand ``Floating`` class to include operations that allow for better
-  precision: ``log1p``, ``expm1``, ``log1pexp`` and ``log1mexp``. These are not
-  available from ``Prelude``, but the full class is exported from ``Numeric``.
-
-- Add ``Data.List.NonEmpty`` and ``Data.Semigroup`` (to become
-  super-class of ``Monoid`` in the future). These modules were
-  provided by the ``semigroups`` package previously. (:ghc-ticket:`10365`)
-
-- The constraints of various functions in ``Control.Monad`` have been
-  generalized from ``Monad`` to ``Applicative`` including ``filterM``,
-  ``zipWithM`` and ``replicateM_`` (see :ghc-ticket:`10168`).
-
-- Add ``GHC.TypeLits.TypeError`` and ``ErrorMessage`` to allow users
-  to define custom compile-time error messages. (see :ref:`custom-errors` and
-  the original :ghc-wiki:`proposal <Proposal/CustomTypeErrors>`).
-
-- The datatypes in ``GHC.Generics`` now have ``Enum``, ``Bounded``, ``Ix``,
-  ``Functor``, ``Applicative``, ``Monad``, ``MonadFix``, ``MonadPlus``, ``MonadZip``,
-  ``Foldable``, ``Foldable``, ``Traversable``, ``Generic1``, and ``Data`` instances
-  as appropriate. (:ghc-ticket:`9043`)
-
-- The ``Generic`` instance for ``Proxy`` is now poly-kinded (see :ghc-ticket:`10775`)
-
-- The ``IsString`` instance for ``[Char]`` has been modified to eliminate
-  ambiguity arising from overloaded strings and functions like ``(++)``.
-
-- Move ``Const`` from ``Control.Applicative`` to its own module in
-  ``Data.Functor.Const``. (see :ghc-ticket:`11135`)
-
-- Enable ``PolyKinds`` in the ``Data.Functor.Const`` module to give ``Const``
-  the kind ``* -> k -> *`` (see :ghc-ticket:`10039`).
-
-- Add the ``TypeError`` datatype to ``Control.Exception``, which represents the
-  error that is thrown when an expression fails to typecheck when run using
-  :ghc-flag:`-fdefer-type-errors`. (see :ghc-ticket:`10284`)
-
-binary
-~~~~~~
-
--  Version number XXXXX (was 0.7.1.0)
-
-bytestring
-~~~~~~~~~~
-
--  Version number XXXXX (was 0.10.4.0)
-
-Cabal
-~~~~~
-
--  Version number XXXXX (was 1.18.1.3)
-
-containers
-~~~~~~~~~~
-
--  Version number XXXXX (was 0.5.4.0)
-
-deepseq
-~~~~~~~
-
--  Version number XXXXX (was 1.3.0.2)
-
-directory
-~~~~~~~~~
-
--  Version number XXXXX (was 1.2.0.2)
-
-filepath
-~~~~~~~~
-
--  Version number XXXXX (was 1.3.0.2)
-
-ghc
-~~~
-
--  TODO FIXME.
-
--  The ``HsBang`` type has been removed in favour of ``HsSrcBang`` and
-   ``HsImplBang``. Data constructors now always carry around their
-   strictness annotations as the user wrote them, whether from an
-   imported module or not.
-
--  Moved ``startsVarSym``, ``startsVarId``, ``startsConSym``, ``startsConId``,
-   ``startsVarSymASCII``, and ``isVarSymChar`` from ``Lexeme`` to the
-   ``GHC.Lemexe`` module of the ``ghc-boot`` library.
-
--  Add ``isImport``, ``isDecl``, and ``isStmt`` functions.
-
--  The `mi_fix_fn` field of `ModIface` had its type changed from
-   ``OccName -> Fixity`` to ``OccName -> Maybe Fixity``, where a returned value
-   of ``Nothing`` indicates a cache miss. As a result, the types of
-   ``mkIfaceFixCache`` and ``emptyIfaceFixCache`` were also changed to have a
-   return type of ``Maybe Fixity``, and a new ``mi_fix :: OccName -> Fixity``
-   function was introduced which invokes ``mi_fix_fn`` but returns
-   ``defaultFixity`` upon a cache miss.
-
-ghc-boot
-~~~~~~~~
-
--  This is an internal package. Use with caution.
-
--  This package was renamed from ``bin-package-db`` to reflect its new purpose
-   of containing intra-GHC functionality that needs to be shared across
-   multiple GHC boot libraries.
-
--  Added ``GHC.Lexeme``, which contains functions for determining if a
-   character can be the first letter of a variable or data constructor in
-   Haskell, as defined by GHC. (These functions were moved from ``Lexeme``
-   in ``ghc``.)
-
--  Added ``GHC.LanguageExtensions`` which contains a type listing all
-   supported language extensions.
-
-ghc-prim
-~~~~~~~~
-
--  Version number XXXXX (was 0.3.1.0)
-
-haskell98
-~~~~~~~~~
-
--  Version number XXXXX (was 2.0.0.3)
-
-haskell2010
-~~~~~~~~~~~
-
--  Version number XXXXX (was 1.1.1.1)
-
-hoopl
-~~~~~
-
--  Version number XXXXX (was 3.10.0.0)
-
-hpc
-~~~
-
--  Version number XXXXX (was 0.6.0.1)
-
-integer-gmp
-~~~~~~~~~~~
-
--  Version number XXXXX (was 0.5.1.0)
-
-old-locale
-~~~~~~~~~~
-
--  Version number XXXXX (was 1.0.0.6)
-
-old-time
-~~~~~~~~
-
--  Version number XXXXX (was 1.1.0.2)
-
-process
-~~~~~~~
-
--  Version number XXXXX (was 1.2.0.0)
-
-template-haskell
-~~~~~~~~~~~~~~~~
-
--  Version number XXXXX (was 2.9.0.0)
-
--  The ``Lift`` type class for lifting values into Template Haskell
-   splices now has a default signature ``lift :: Data a => a -> Q Exp``,
-   which means that you do not have to provide an explicit
-   implementation of ``lift`` for types which have a ``Data`` instance.
-   To manually use this default implementation, you can use the
-   ``liftData`` function which is now exported from
-   ``Language.Haskell.TH.Syntax``.
-
--  ``Info``'s constructors no longer have ``Fixity`` fields. A
-   ``qReifyFixity`` function was added to the ``Quasi`` type class (as
-   well as the ``reifyFixity`` function, specialized for ``Q``) to allow
-   lookup of fixity information for any given ``Name``.
-
-time
-~~~~
-
--  Version number XXXXX (was 1.4.1)
-
-unix
-~~~~
-
--  Version number XXXXX (was 2.7.0.0)
-
-Win32
-~~~~~
-
--  Version number XXXXX (was 2.3.0.1)
-
-Known bugs
-----------
-
--  TODO FIXME
diff --git a/docs/users_guide/8.2.1-notes.rst b/docs/users_guide/8.2.1-notes.rst
new file mode 100644 (file)
index 0000000..957552b
--- /dev/null
@@ -0,0 +1,193 @@
+.. _release-8-2-1:
+
+Release notes for version 8.2.1
+===============================
+
+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 branch.
+
+Highlights
+----------
+
+The highlights since the 8.0 branch are:
+
+- TODO FIXME
+
+Full details
+------------
+
+Language
+~~~~~~~~
+
+-  TODO FIXME.
+
+Compiler
+~~~~~~~~
+
+-  TODO FIXME.
+
+GHCi
+~~~~
+
+-  TODO FIXME.
+
+Template Haskell
+~~~~~~~~~~~~~~~~
+
+-  TODO FIXME.
+
+Runtime system
+~~~~~~~~~~~~~~
+
+-  TODO FIXME.
+
+Build system
+~~~~~~~~~~~~
+
+-  TODO FIXME.
+
+Package system
+~~~~~~~~~~~~~~
+
+-  TODO FIXME.
+
+hsc2hs
+~~~~~~
+
+-  TODO FIXME.
+
+Libraries
+---------
+
+array
+~~~~~
+
+-  Version number XXXXX (was 0.5.0.0)
+
+
+.. _lib-base:
+
+base
+~~~~
+
+See ``changelog.md`` in the ``base`` package for full release notes.
+
+-  Version number 4.10.0.0 (was 4.9.0.0)
+
+binary
+~~~~~~
+
+-  Version number XXXXX (was 0.7.1.0)
+
+bytestring
+~~~~~~~~~~
+
+-  Version number XXXXX (was 0.10.4.0)
+
+Cabal
+~~~~~
+
+-  Version number XXXXX (was 1.18.1.3)
+
+containers
+~~~~~~~~~~
+
+-  Version number XXXXX (was 0.5.4.0)
+
+deepseq
+~~~~~~~
+
+-  Version number XXXXX (was 1.3.0.2)
+
+directory
+~~~~~~~~~
+
+-  Version number XXXXX (was 1.2.0.2)
+
+filepath
+~~~~~~~~
+
+-  Version number XXXXX (was 1.3.0.2)
+
+ghc
+~~~
+
+-  TODO FIXME.
+
+ghc-boot
+~~~~~~~~
+
+-  This is an internal package. Use with caution.
+
+-  TODO FIXME.
+
+ghc-prim
+~~~~~~~~
+
+-  Version number XXXXX (was 0.3.1.0)
+
+haskell98
+~~~~~~~~~
+
+-  Version number XXXXX (was 2.0.0.3)
+
+haskell2010
+~~~~~~~~~~~
+
+-  Version number XXXXX (was 1.1.1.1)
+
+hoopl
+~~~~~
+
+-  Version number XXXXX (was 3.10.0.0)
+
+hpc
+~~~
+
+-  Version number XXXXX (was 0.6.0.1)
+
+integer-gmp
+~~~~~~~~~~~
+
+-  Version number XXXXX (was 0.5.1.0)
+
+old-locale
+~~~~~~~~~~
+
+-  Version number XXXXX (was 1.0.0.6)
+
+old-time
+~~~~~~~~
+
+-  Version number XXXXX (was 1.1.0.2)
+
+process
+~~~~~~~
+
+-  Version number XXXXX (was 1.2.0.0)
+
+template-haskell
+~~~~~~~~~~~~~~~~
+
+-  Version number XXXXX (was 2.9.0.0)
+
+time
+~~~~
+
+-  Version number XXXXX (was 1.4.1)
+
+unix
+~~~~
+
+-  Version number XXXXX (was 2.7.0.0)
+
+Win32
+~~~~~
+
+-  Version number XXXXX (was 2.3.0.1)
+
+Known bugs
+----------
+
+-  TODO FIXME
index 60f8c9a..b7ff4c0 100644 (file)
@@ -12,7 +12,7 @@ Contents:
 
    license
    intro
-   8.0.1-notes
+   8.2.1-notes
    ghci
    runghc
    usage