add a changelog and update the document for ORC (#20415)

* add a changelog and update the document for ORC

* hone

* back

* Apply suggestions from code review

Co-authored-by: Clay Sweetser <Varriount@users.noreply.github.com>

* Update doc/mm.md

Co-authored-by: Clay Sweetser <Varriount@users.noreply.github.com>

* Update doc/mm.md

Co-authored-by: Clay Sweetser <Varriount@users.noreply.github.com>
Co-authored-by: Andreas Rumpf <rumpf_a@web.de>

changelog.md

@@ -50,6 +50,9 @@
 - Static linking against OpenSSL versions below 1.1, previously done by
   setting `-d:openssl10`, is no longer supported.
 
+- ORC is now the default memory management strategy. Use
+  `--mm:refc` for a transition period.
+
 ## Standard library additions and changes
 
 [//]: # "Changes:"

doc/advopt.txt

@@ -127,8 +127,7 @@ Advanced options:
   --skipParentCfg:on|off    do not read the parent dirs' configuration files
   --skipProjCfg:on|off      do not read the project's configuration file
   --mm:orc|arc|refc|markAndSweep|boehm|go|none|regions
-                            select which memory management to use; default is 'refc'
+                            select which memory management to use; default is 'orc'
-                            recommended is 'orc'
   --exceptions:setjmp|cpp|goto|quirky
                             select the exception handling implementation
   --index:on|off            turn index file generation on|off

doc/mm.md

@@ -28,10 +28,10 @@ To choose the memory management strategy use the `--mm:` switch.
 ARC/ORC
 -------
 
-`--mm:orc` is a memory management mode primarily based on reference counting. Cycles
+ORC is the default memory management strategy. It is a memory
-in the object graph are handled by a "cycle collector" which is based on "trial deletion".
+management mode primarily based on reference counting. Reference cycles are
-Since algorithms based on "tracing" are not used, the runtime behavior is oblivious to
+handled by a cycle collection mechanism based on "trial deletion".
-the involved heap sizes.
+Since algorithms based on "tracing" are not used, the runtime behavior is oblivious to the involved heap and stack sizes.
 
 The reference counting operations (= "RC ops") do not use atomic instructions and do not have to --
 instead entire subgraphs are *moved* between threads. The Nim compiler also aggressively
@@ -57,12 +57,11 @@ and leaks memory with `--mm:arc`, in other words, for `async` you need to use `-
 Other MM modes
 --------------
 
-.. note:: The default `refc` GC is incremental, thread-local and not "stop-the-world".
+.. note:: The `refc` GC is incremental, thread-local and not "stop-the-world".
 
---mm:refc    This is the default memory management strategy. It's a
+--mm:refc    It's a deferred reference counting based garbage collector
-  deferred reference counting based garbage collector
+  with a simple Mark&Sweep backup GC in order to collect cycles.
-  with a simple Mark&Sweep backup GC in order to collect cycles. Heaps are thread-local.
+  Heaps are thread-local. [This document](refc.html) contains further information.
-  [This document](refc.html) contains further information.
 --mm:markAndSweep  Simple Mark-And-Sweep based garbage collector.
   Heaps are thread-local.
 --mm:boehm    Boehm based garbage collector, it offers a shared heap.