doc/next: tweak runtime release notes

- Add section headings to make the section easier to read.
- Reorder features to better reflect their impact and importance.
- Tweak some awkward wording here and there.

Change-Id: If72c526f4b3a26a7a4584d6c59857db02c0c1338
Reviewed-on: https://go-review.googlesource.com/c/go/+/676818
Reviewed-by: Michael Pratt <mpratt@google.com>
Auto-Submit: Michael Knyszek <mknyszek@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>

diff --git a/doc/next/4-runtime.md b/doc/next/4-runtime.md
index 67c1cee401a7e69b58f56657174e7d92afa231a7..ef679a51eefb252ada479f3fff96224297e5a567 100644 (file)
--- a/doc/next/4-runtime.md
+++ b/doc/next/4-runtime.md
@@ -1,21 +1,6 @@
 ## Runtime {#runtime}
 
-<!-- go.dev/issue/71517 -->
-
-The message printed when a program exits due to an unhandled panic
-that was recovered and repanicked no longer repeats the text of
-the panic value.
-
-Previously, a program which panicked with `panic("PANIC")`,
-recovered the panic, and then repanicked with the original
-value would print:
-
-    panic: PANIC [recovered]
-      panic: PANIC
-
-This program will now print:
-
-    panic: PANIC [recovered, repanicked]
+### Container-aware `GOMAXPROCS`
 
 <!-- go.dev/issue/73193 -->
 
@@ -42,6 +27,43 @@ respectively.
 In order to support reading updated cgroup limits, the runtime will keep cached
 file descriptors for the cgroup files for the duration of the process lifetime.
 
+### New experimental garbage collector
+
+<!-- go.dev/issue/73581 -->
+
+A new garbage collector is now available as an experiment. This garbage
+collector's design improves the performance of marking and scanning small objects
+through better locality and CPU scalability. Benchmark result vary, but we expect
+somewhere between a 10—40% reduction in garbage collection overhead in real-world
+programs that heavily use the garbage collector.
+
+The new garbage collector may be enabled by setting `GOEXPERIMENT=greenteagc`
+at build time. We expect the design to continue to evolve and improve. To that
+end, we encourage Go developers to try it out and report back their experiences.
+See the [GitHub issue](/issue/73581) for more details on the design and
+instructions for sharing feedback.
+
+### Change to unhandled panic output
+
+<!-- go.dev/issue/71517 -->
+
+The message printed when a program exits due to an unhandled panic
+that was recovered and repanicked no longer repeats the text of
+the panic value.
+
+Previously, a program which panicked with `panic("PANIC")`,
+recovered the panic, and then repanicked with the original
+value would print:
+
+    panic: PANIC [recovered]
+      panic: PANIC
+
+This program will now print:
+
+    panic: PANIC [recovered, repanicked]
+
+### VMA names on Linux
+
 <!-- go.dev/issue/71546 -->
 
 On Linux systems with kernel support for anonymous VMA names
@@ -49,15 +71,3 @@ On Linux systems with kernel support for anonymous VMA names
 mappings with context about their purpose. e.g., `[anon: Go: heap]` for heap
 memory. This can be disabled with the [GODEBUG setting](/doc/godebug)
 `decoratemappings=0`.
-
-<!-- go.dev/issue/73581 -->
-
-A new experimental garbage collector is now available as an experiment. The
-new design aims to improve the efficiency of garbage collection through better
-locality and CPU scalability in the mark algorithm. Benchmark result vary, but
-we expect somewhere between a 10—40% reduction in garbage collection overhead
-in real-world programs that heavily use the garbage collector.
-
-The new garbage collector may be enabled by setting `GOEXPERIMENT=greenteagc`
-at build time. See the [GitHub issue](/issue/73581) for more details on the design
-and instructions on how to report feedback.