Start 9.6.1-notes

Updates the documentation notes to start tracking changes for
the 9.6.1 release (instead of 9.4).

3 files changed, 25 insertions, 435 deletions

diff --git a/docs/users_guide/9.4.1-notes.rst b/docs/users_guide/9.4.1-notes.rst
deleted file mode 100644
index 62cd9c63fd..0000000000
--- a/docs/users_guide/9.4.1-notes.rst
+++ /dev/null
@@ -1,434 +0,0 @@
-.. _release-9-4-1:
-
-Version 9.4.1
-==============
-
-The significant changes to the various parts of the compiler are listed in the
-following sections.
-
-The :ghc-flag:`LLVM backend <-fllvm>` of this release is to be used with LLVM
-10, 11, 12, or 13.
-
-Language
-~~~~~~~~
-
-- A small change has been made to the way GHC infers types for definitions
-  with no type signature: GHC will no longer generalize a function over
-  a type variable determined by a functional dependency. For example::
-
-    class C a b | a -> b where
-      op :: a -> b -> ()
-    f x = op True x
-
-  Previously, GHC inferred ``f :: C Bool b => b -> ()``. However, the functional
-  dependency says that only one type could ever be used for ``b``: this function
-  is hardly valid "for all" ``b``\ s. With the change, GHC will reject, looking
-  for the (non-existent) instance for ``C Bool b``.
-
-  If you want to retain the old behavior, add a (backward-compatible) type signature,
-  explicitly requesting this unusual quantification.
-
-- GHC Proposal `#371 <https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0371-non-magical-eq.md>`_ has been implemented. This means:
-
-  * The use of equality constraints no longer requires ``-XGADTs`` or ``-XTypeFamilies``.
-
-  * The use of equality constraint syntax ``a ~ b`` requires ``-XTypeOperators``,
-    otherwise results in a warning (:ghc-flag:`-Wtype-equality-requires-operators`).
-
-  * ``(~)`` is now a legal name for a user-defined type operator:
-    ::
-
-      class a ~ b where
-        ...
-
-    This used to be rejected with "Illegal binding of built-in syntax".
-
-  * The built-in type equality is now exported from ``Data.Type.Equality`` and
-    re-exported from ``Prelude``. When ``(~)`` is not in scope, its use results
-    in a warning (:ghc-flag:`-Wtype-equality-out-of-scope`).
-
-- GHC Proposal `#302 <https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0302-cases.rst>`_ has been implemented.
-  This means under ``-XLambdaCase``, a new expression heralded by ``\cases`` is
-  available, which works like ``\case`` but can match on multiple patterns.
-  This means constructor patterns with arguments have to parenthesized here,
-  just like in lambda expressions.
-
-- There were previously cases around functional dependencies and injective
-  type families where the result of type inference would depend on the order
-  of constraints, as written in a source file. These cases are fundamentally ambiguous.
-  While GHC previously made an arbitrary decision, it now notices the ambiguity
-  and rejects the program. This means that some previously accepted programs are
-  now rejected. The solution is to add a type annotation or type application to
-  resolve the ambiguity.
-
-  This is the fix for :ghc-ticket:`18851`.
-
-Compiler
-~~~~~~~~
-
-- The compiler now accepts arguments via GNU-style response files
-  (:ghc-ticket:`16476`).
-
-- New :ghc-flag:`-Wredundant-strictness-flags` that checks for strictness flags
-  (``!``) applied to unlifted types, which are always strict.
-
-- New :ghc-flag:`-Wforall-identifier` (enabled by default) that warns against
-  using the name ``forall`` as an identifer on the term level.
-
-- New :ghc-flag:`-fprof-late` that adds automatic CCS annotations to all
-  top level functions *after* core optimisation have been run.
-
-- Typechecking plugins now support type-family rewriting. The ``TcPlugin``
-  datatype now contains an extra field, ``tcPluginRewrite``, which allows
-  typechecking plugin authors to specify which type families should be
-  rewritten by the plugin, returning for each type family application a
-  ``TcPluginRewriteResult``.
-  In addition, typechecking plugins now have the ability to emit new constraints
-  at the same time as contradictions. To account for these changes, the
-  ``TcPluginResult`` datatype has been renamed to ``TcPluginSolveResult``,
-  which bundles pattern synonyms ``TcPluginOk`` and ``TcPluginContradiction``
-  to recover the old interface.
-
-- A new type of plugin: defaulting plugins. These plugins can propose
-  defaults for ambiguous variables that would otherwise cause errors
-  just like the built-in defaulting mechanism.
-
-- ``GHC.Plugins.parsedResultAction`` now takes and returns a value of type
-  ``ParsedResult``, containing the ``HsParsedModule`` as well as ``PsMessages``,
-  which contains warnings and errors encountered by the parser before
-  they're shown to the user, as long as none of the errors prevented the AST
-  from being built. This means plugins can remove, modify, or add any of these,
-  or simply pass them through unchanged.
-
-- The way GHC checks for representation polymorphism has been overhauled:
-  all the checks are now done during typechecking. The error messages
-  now contain more detailed information about the specific check that was performed.
-- A new pragma, :pragma:`OPAQUE`, that ensures that every call of a named function
-  annotated with an :pragma:`OPAQUE` pragma remains a call of that named function,
-  not some name-mangled variant.
-
-- The parsing of implicit parameters is slightly more permissive, as GHC now allows ::
-
-      foo :: (?ip :: forall a. a -> a)
-
-  without requiring parentheses around ``forall a. a -> a``. Note that implicit
-  parameters with such kinds are unlikely to be very useful, due to
-  :ghc-ticket:`18759`.
-
-- Changes to the treatment of :extension:`UnboxedSums`:
-
-  - GHC can now parse unboxed sum type constructors ``(# | #)``, ``(# | | #)``,
-    ``(# | | | #)``, etc. Partial applications need to be written in prefix form,
-    e.g. ``(# | #) Int#``.
-
-  - Unboxed sums now require the :extension:`UnboxedSums` extension to be enabled.
-
-  - The :extension:`UnboxedTuples` extension now implies
-    :extension:`UnboxedSums`. This means that code using unboxed sums that
-    enabled the :extension:`UnboxedTuples` extension but didn't explicitly
-    enable :extension:`UnboxedSums` will continue to work without changes.
-
-- Constructed Product Result analysis (c.f. :ghc-flag:`-fcpr-anal`) has been
-  overhauled and will now unbox nestedly, if termination properties of the
-  function permit. This allows unboxing of constructed results returned by
-  ``IO`` actions. E.g.::
-
-      sumIO :: [Int] -> IO Int
-      sumIO []     = return 0
-      sumIO (x:xs) = do
-        r <- sumIO xs
-        return $! x + r
-
-  Note the use of ``$!``: Without it, GHC would be unable to see that evaluation
-  of ``r`` and ``x`` terminates (and rapidly, at that). An alternative would be to
-  evaluate both with a bang pattern or a ``seq``, but the ``return $! <res>``
-  idiom should work more reliably and needs less thinking.
-
-- Demand analysis (cf. :ghc-flag:`-fstrictness`) now integrates a
-  Boxity Analysis that tracks whether a function needs a parameter boxed. If
-  that is the case, the worker/wrapper transformation (cf.
-  :ghc-flag:`-fworker-wrapper`) will not unbox that parameter, leading to less
-  reboxing in many cases.
-
-  For reasons of backwards-compatible performance, you may find that the new
-  mechanism is too aggressive in a few cases (e.g., still unboxing a parameter
-  that is used boxed in a hot path). Do post a bug report with your example!
-  Then wrap the uses of the parameter in ``GHC.Exts.lazy`` for a short-term fix.
-
-- Tag inference has been implemented.
-
-  It's a new backend optimization pass aimed at avoiding
-  redundant evaluatedness checks. The basic pass is always enabled and not optional.
-  When using :ghc-flag:`-fworker-wrapper-cbv` it additionally will generate workers for functions
-  with strict arguments, pushing the evaluation+tagging of the arguments into the wrapper
-  and allowing the worker to simply assume all arguments are fully evaluated and properly
-  tagged. Usually the wrapper will then inline, and if the argument is known to be properly
-  tagged at the call site the wrapper will become a no-op. Giving us a more efficient
-  worker without adding any overhead. If the argument *isn't* known to be evaluated we
-  perform the same amount of work, but do it at call sites instead of inside the called
-  function.
-
-  In general :ghc-flag:`-fworker-wrapper-cbv` is very beneficial and can be safely enabled.
-  However sadly there are two exceptions. It can break rules for code which made assumptions about
-  which functions get a W/W split which now no longer hold.
-  See :ghc-ticket:`20364` for the details. For this reason it isn't enabled by default.
-  For code which has the proper ``INLINABLE`` (:ref:`inlinable-pragma`) and ``INLINE`` (:ref:`inline-pragma`)
-  or that doesn't define any rule-relevant functions this shouldn't happen. The longterm fix here is to
-  apply the proper pragmas.
-  There is also a known issue where a function taking multiple unlifted arguments can cause excessive
-  spilling (:ghc-ticket:`20334`). This seems to be an edge case. But if you think you are hitting this case please
-  comment on the ticket so that we can prioritize it accordingly.
-
-- Support for Sun SPARC architecture has been dropped (:ghc-ticket:`16883`).
-
-- A fix for GHC's handling of the XDG Base Directory Specification
-  (:ghc-ticket:`6077`, :ghc-ticket:`20684`, :ghc-ticket:`20669`,
-  :ghc-ticket:`20660`):
-
-  - For the package database previously in ``~/.ghc/<arch-ver>``, we will
-    continue to use the old path if it exists. For example, if the
-    ``~/.ghc/x86_64-linux-9.4.1`` directory exists, GHC will use that for its
-    user package database. If this directory does not exist, we will use
-    ``$XDG_DATA_HOME/ghc/x86_64-linux-9.4.1``. This is in order to give tooling
-    like cabal time to migrate
-
-  - For GHCi configuration files previously located in ``~/.ghc/`` like
-    ``ghci.conf`` and ``ghci_history``, we will first check if they exist in
-    ``~/.ghc`` and use those if they do. However, we will create new files like
-    ``ghci_history`` only in ``$XDG_DATA_HOME/ghc``. So if you don't have a
-    previous GHC installation which created ``~/.ghc/ghci_history``, the
-    history file will be written to ``$XDG_DATA_HOME/ghc``. If you already have
-    an older GHC installation which wrote ``~/.ghc/ghci_history``, then GHC
-    will continue to write the history to that file.
-
-- The :ghc-flag:`-Wunticked-promoted-constructors` warning is no longer
-  enabled with :ghc-flag:`-Wall` (:ghc-ticket:`20531`), as a part of
-  long-term push towards Dependent Haskell.
-
-- In GHCi, the :ghci-cmd:`:type` command no longer instantiates quantified
-  type variables when given a polymorphic type. (It used to instantiate
-  inferred type variables.)
-
-Runtime system
-~~~~~~~~~~~~~~~~
-
-- Support for GHC's eventlog is now enabled in all runtime system configurations,
-  eliminating the need to pass the :ghc-flag:`-eventlog` flag to use the eventlog.
-  This flag has been deprecated (:ghc-ticket:`18948`).
-
-``base`` library
-~~~~~~~~~~~~~~~~
-
-- There's a new special function ``withDict`` in ``GHC.Exts``: ::
-
-        withDict :: forall {rr :: RuntimeRep} st dt (r :: TYPE rr). st -> (dt => r) -> r
-
-  where ``dt`` must be a class containing exactly one method, whose type
-  must be ``st``.
-
-  This function converts ``st`` to a type class dictionary.
-  It removes the need for ``unsafeCoerce`` in implementation of reflection
-  libraries. It should be used with care, because it can introduce
-  incoherent instances.
-
-  For example, the ``withTypeable`` function from the
-  ``Data.Typeable`` module can now be defined as: ::
-
-        withTypeable :: forall k (a :: k) rep (r :: TYPE rep). ()
-                     => TypeRep a -> (Typeable a => r) -> r
-        withTypeable rep k = withDict @(TypeRep a) @(Typeable a) rep k
-
-  Note that the explicit type applications are required, as the call to
-  ``withDict`` would be ambiguous otherwise.
-
-  This replaces the old ``GHC.Exts.magicDict``, which required
-  an intermediate data type and was less reliable.
-
-``ghc-prim`` library
-~~~~~~~~~~~~~~~~~~~~
-
-- Primitive types and functions which handle boxed values are now levity-polymorphic,
-  meaning that they now also work with unlifted boxed values (i.e. values whose type
-  has kind ``TYPE (BoxedRep Unlifted)``).
-
-  The following type constructors are now levity-polymorphic:
-
-    - ``Array#``, ``SmallArray#``, ``Weak#``, ``StablePtr#``, ``StableName#``,
-
-    - ``MutableArray#``, ``SmallMutableArray#``, ``MutVar#``,
-      ``TVar#``, ``MVar#``, ``IOPort#``.
-
-  For example, ``Array#`` used to have kind: ::
-
-        Type -> UnliftedType
-
-  but it now has kind: ::
-
-        forall {l :: Levity}. TYPE (BoxedRep l) -> UnliftedType
-
-  Similarly, ``MutVar#`` used to have kind: ::
-
-        Type -> Type -> UnliftedType
-
-  but it now has kind: ::
-
-        forall {l :: Levity}. Type -> TYPE (BoxedRep l) -> UnliftedType
-
-  This means that in ``Array# a``, ``MutableArray# s a``, ``MutVar# s a``, ...,
-  the element type ``a``, must always be boxed, but it can now either be lifted
-  or unlifted.
-  In particular, arrays and mutable variables can now be used to store
-  other arrays and mutable variables.
-
-  All functions which use these updated primitive types are also levity-polymorphic:
-
-    - all array operations (reading/writing/copying/...), for both arrays and small arrays,
-      mutable and immutable:
-
-      - ``newArray#``, ``readArray#``, ``writeArray#``, ``sizeofArray#``, ``sizeofMutableArray#``, ``indexArray#``,
-        ``unsafeFreezeArray#``, ``unsafeThawArray#``, ``copyArray#``, ``copyMutableArray#``, ``cloneArray#``,
-        ``cloneMutableArray#``, ``freezeArray#``, ``thawArray#``, ``casArray#``,
-
-      - ``newSmallArray#``, ``shrinkSmallMutableArray#``, ``readSmallArray#``, ``writeSmallArray#``, ``sizeofSmallArray#``,
-        ``getSizeofSmallMutableArray#``, ``indexSmallArray#``, ``unsafeFreezeSmallArray#``,
-        ``unsafeThawSmallArray#``, ``copySmallArray#``, ``copySmallMutableArray#``, ``cloneSmallArray#``,
-        ``cloneSmallMutableArray#``, ``freezeSmallArray#``, ``thawSmallArray#``, ``casSmallArray#``,
-
-    - ``newMutVar#``, ``readMutVar#``, ``writeMutVar#``, ``casMutVar#``,
-
-    - operations on ``MVar#`` and ``TVar#``:
-
-      - ``newTVar#``, ``readTVar#``, ``readTVarIO#``, ``writeTVar#``,
-
-      - ``newMVar#``, ``takeMVar#``, ``tryTakeMVar#``, ``putMVar#``,
-        ``tryPutMVar#``, ``readMVar#``, ``tryReadMVar#``,
-
-    - ``STM`` operations ``atomically#``, ``retry#``, ``catchRetry#`` and ``catchSTM#``.
-
-    - ``newIOPort#``, ``readIOPort#``, ``writeIOPort#``,
-
-    - ``mkWeak#``, ``mkWeakNoFinalizer#``, ``addCFinalizerToWeak#``, ``deRefWeak#``, ``finalizeWeak#``,
-
-    - ``makeStablePtr#``, ``deRefStablePtr#``, ``eqStablePtr#``, ``makeStableName#``, ``stableNameToInt#``,
-
-  For example, the full type of ``newMutVar#`` is now: ::
-
-        newMutVar#
-          :: forall {l :: Levity} s (a :: TYPE (BoxedRep l)).
-             a -> State# s -> (# State# s, MVar# s a #)
-
-  and the full type of ``writeSmallArray#`` is: ::
-
-        writeSmallArray#
-          :: forall {l :: Levity} s (a :: TYPE (BoxedRep l)).
-             SmallMutableArray# s a -> Int# -> a -> State# s -> State# s
-
-- ``ArrayArray#`` and ``MutableArrayArray#`` have been moved from ``GHC.Prim`` to ``GHC.Exts``.
-  They are deprecated, because their functionality is now subsumed by ``Array#``
-  and ``MutableArray#``.
-
-- ``mkWeak#``, ``mkWeakNoFinalizer#``, ``touch#``
-  and ``keepAlive#`` are now levity-polymorphic instead of
-  representation-polymorphic. For instance: ::
-
-        mkWeakNoFinalizer#
-          :: forall {l :: Levity} {k :: Levity}
-                    (a :: TYPE (BoxedRep l))
-                    (b :: TYPE (BoxedRep k)).
-             a -> b -> State# RealWorld -> (# State# RealWorld, Weak# b #)
-
-  That is, the type signature now quantifies over the ``GHC.Exts.Levity`` of ``a``
-  instead of its ``GHC.Exts.RuntimeRep``. In addition, this variable is now inferred,
-  instead of specified, meaning that it is no longer eligible for visible type application.
-  Note that ``b`` is now also levity-polymorphic, due to the change outlined in the
-  previous point.
-
-- Primitive functions for throwing and catching exceptions are now more polymorphic
-  than before. For example, ``catch#`` now has type: ::
-
-        catch#
-          :: forall {r :: RuntimeRep} {l :: Levity}
-                    (a :: TYPE r)
-                    (b :: TYPE (BoxedRep l)).
-              ( State# RealWorld -> (# State# RealWorld, a #) )
-          -> ( b -> State# RealWorld -> (# State# RealWorld, a #) )
-          -> State# RealWorld -> (# State# RealWorld, a #)
-
-  The following functions have been generalised in this way:
-
-    - ``catch#``,
-
-    - ``raise#``, ``raiseIO#``,
-
-    - ``maskAsyncExceptions#``, ``maskUninterruptible#``, ``unmaskAsyncExceptions#``.
-
-  Note in particular that ``raise#`` is now both representation-polymorphic
-  (with an inferred `RuntimeRep` argument) and levity-polymorphic, with type: ::
-
-      raise# :: forall {l :: Levity} {r :: RuntimeRep}
-                       (a :: TYPE (BoxedRep l))
-                       (b :: TYPE r).
-                a -> b
-
-- ``fork#`` and ``forkOn#`` are now representation-polymorphic. For example, ``fork#``
-  now has type: ::
-
-      fork# :: forall {r :: RuntimeRep} (a :: TYPE r).
-               (State# RealWorld -> (# State# RealWorld, a #))
-            -> (State# RealWorld -> (# State# RealWorld, a #))
-
-- ``GHC.Exts.reallyUnsafePtrEquality#`` has been made more general, as it is now
-  both levity-polymorphic and heterogeneous: ::
-
-        reallyUnsafePtrEquality#
-          :: forall {l :: Levity} {k :: Levity}
-                    (a :: TYPE (BoxedRep l))
-                    (b :: TYPE (BoxedRep k))
-          . a -> b -> Int#
-
-  This means that ``GHC.Exts.reallyUnsafePtrEquality#`` can be used
-  on primitive arrays such as ``GHC.Exts.Array#`` and ``GHC.Exts.ByteArray#``.
-  It can also be used on values of different types, without needing to call
-  ``GHC.Exts.unsafeCoerce#``.
-
-- Added ``GHC.Exts.reallyUnsafePtrEquality`` which recovers the
-  previous behaviour of ``GHC.Exts.reallyUnsafePtrEquality#``: ::
-
-        reallyUnsafePtrEquality :: forall (a :: Type). a -> a -> Int#
-
-- Added ``GHC.Exts.sameArray#``, ``GHC.Exts.sameSmallArray#``,
-  ``GHC.Exts.sameByteArray#`` and ``GHC.Exts.sameArrayArray#``: ::
-
-        sameArray# :: Array# a -> Array# a -> Int#
-        sameSmallArray# :: SmallArray# a -> SmallArray# a -> Int#
-        sameByteArray# :: ByteArray# -> ByteArray# -> Int#
-        sameArrayArray# :: ArrayArray# -> ArrayArray# -> Int#
-
-``ghc`` library
-~~~~~~~~~~~~~~~
-
-- A new ``GHC.Hs.Syn.Type`` module has been introduced which defines functions
-  for computing the ``Type`` of an ``HsExpr GhcTc`` in a pure fashion.
-  The ``hsLitType`` and ``hsPatType`` functions that previously lived in
-  ``GHC.Tc.Utils.Zonk`` have been moved to this module.
-
-- A ``Typeable`` constraint has been added to ``fromStaticPtr`` in the
-  class ``GHC.StaticPtr.IsStatic``. GHC automatically wraps each use of
-  the ``static`` keyword with ``fromStaticPtr``. Because ``static`` requires
-  its argument to be an instance of ``Typeable``, ``fromStaticPtr`` can
-  safely carry this constraint as well.
-
-- The ``newWanted`` function exported by ``GHC.Tc.Plugin`` now passes on
-  the full ``CtLoc`` instead of reconstituting it from the type-checking
-  environment. This makes ``newWanted`` consistent with ``newGiven``.
-  For authors of type-checking plugins, this means you don't need to wrap
-  a call to ``newWanted`` in ``setCtLocM`` to create a new Wanted constraint
-  with the provided ``CtLoc``.
-
-- GHC no longer carries ``Derived`` constraints. Accordingly, several functions
-  in the plugin architecture that previously passed or received three sets of
-  constraints (givens, deriveds, and wanteds) now work with two such sets.
-
-- A new argument has been added to the ``HsOpTy`` constructor of the ``HsType``
-  datatype, to track the presence of a promotion tick. Plugins which manipulate
-  the Haskell AST will need to take this change into account.
diff --git a/docs/users_guide/9.6.1-notes.rst b/docs/users_guide/9.6.1-notes.rst
new file mode 100644
index 0000000000..c5580b5abe
--- /dev/null
+++ b/docs/users_guide/9.6.1-notes.rst
@@ -0,0 +1,24 @@
+.. _release-9-6-1:
+
+Version 9.6.1
+==============
+
+
+Language
+~~~~~~~~
+
+
+Compiler
+~~~~~~~~
+
+
+``base`` library
+~~~~~~~~~~~~~~~~
+
+
+``ghc-prim`` library
+~~~~~~~~~~~~~~~~~~~~
+
+
+``ghc`` library
+~~~~~~~~~~~~~~~
diff --git a/docs/users_guide/release-notes.rst b/docs/users_guide/release-notes.rst
index a9cb88d078..8c29746c7c 100644
--- a/docs/users_guide/release-notes.rst
+++ b/docs/users_guide/release-notes.rst
@@ -4,4 +4,4 @@ Release notes
 .. toctree::
    :maxdepth: 1
 
-   9.4.1-notes
+   9.6.1-notes