[docs] release notes for !4729 + !3678

Also includes small unrelated type fix

1 files changed, 33 insertions, 1 deletions

diff --git a/docs/users_guide/9.2.1-notes.rst b/docs/users_guide/9.2.1-notes.rst
index 46e174aa03..63543f728b 100644
--- a/docs/users_guide/9.2.1-notes.rst
+++ b/docs/users_guide/9.2.1-notes.rst
@@ -78,7 +78,7 @@ Language
 
 * The :extension:`GHC2021` language is supported now. It builds on top of
   Haskell2010, adding several stable and conservative extensions, and removing
-  deprecated ones. It is now also the “default” langauge set that is active
+  deprecated ones. It is now also the “default” language set that is active
   when no other language set, such as :extension:`Haskell98` or
   :extension:`Haskell2010`,  is explicitly loaded (e.g via Cabal’s
   ``default-language``).
@@ -123,6 +123,15 @@ Language
 Compiler
 ~~~~~~~~
 
+- Performance of the compiler in :ghc-flag:`--make` mode with
+   :ghc-flag:`-j[⟨n⟩]` is significantly improved by improvements to the parallel
+  garbage collector noted below.
+
+  Benchmarks show a 20% decrease in wall clock time, and a 40% decrease in cpu
+  time, when compiling Cabal with ``-j4`` on linux. Improvements are more dramatic
+  with higher parallelism, and we no longer see significant degradation in wall
+  clock time as parallelism increases above 4.
+
 - New :ghc-flag:`-Wredundant-bang-patterns` flag that enables checks for "dead" bangs.
   For instance, given this program: ::
 
@@ -185,6 +194,26 @@ GHCi
 Runtime system
 ~~~~~~~~~~~~~~
 
+- The parallel garbage collector is now significantly more performant. Heavily
+  contended spinlocks have been replaced with mutexes and condition variables.
+  For most programs compiled with the threaded runtime, and run with more than
+  four capabilities, we expect minor GC pauses and GC cpu time both to be reduced.
+
+  For very short running programs (in the order of 10s of milliseconds), we have seen
+  some performance regressions. We recommend programs affected by this to either
+  compile with the single threaded runtime, or otherwise to disable the parallel
+  garbage collector with :rts-flag:`-qg ⟨gen⟩`.
+
+  We don't expect any other performance regressions, however only limited
+  benchmarking has been done. We have only benchmarked GHC and nofib and only on
+  linux.
+
+  Users are advised to reconsider the rts flags that programs are run with. If
+  you have been mitigating poor parallel GC performance by: using large
+  nurseries (:rts-flag:`-A <-A ⟨size⟩>`), disabling load balancing (:rts-flag:`-qb ⟨gen⟩`), or
+  limiting parallel GC to older generations (:rts-flag:`-qg ⟨gen⟩`); then you may
+  find these mitigations are no longer necessary.
+
 - The heap profiler now has proper treatment of pinned ``ByteArray#``\ s. Such
   heap objects will now be correctly attributed to their appropriate cost
   centre instead of merely being lumped into the ``PINNED`` category.
@@ -206,6 +235,9 @@ Runtime system
   is returned is controlled by the :rts-flag:`-Fd ⟨factor⟩`. Memory return
   is triggered by consecutive idle collections.
 
+- The default nursery size, :rts-flag:`-A <-A ⟨size⟩>`, has been increased from
+  1mb to 4mb.
+
 Template Haskell
 ~~~~~~~~~~~~~~~~