7 files changed, 118 insertions, 6 deletions
diff --git a/doc/manual/change-authors.yml b/doc/manual/change-authors.yml
index e18abada1..60c0924c7 100644
--- a/doc/manual/change-authors.yml
+++ b/doc/manual/change-authors.yml
@@ -147,3 +147,6 @@ winter:
 
 yshui:
   github: yshui
+
+zimbatm:
+  github: zimbatm
diff --git a/doc/manual/meson.build b/doc/manual/meson.build
index f53d41b5d..35d94740c 100644
--- a/doc/manual/meson.build
+++ b/doc/manual/meson.build
@@ -126,20 +126,19 @@ manual = custom_target(
     'manual',
     'markdown',
   ],
+  install : true,
+  install_dir : [
+    datadir / 'doc/nix',
+    false,
+  ],
   depfile : 'manual.d',
   env : {
     'RUST_LOG': 'info',
     'MDBOOK_SUBSTITUTE_SEARCH': meson.current_build_dir() / 'src',
   },
 )
-manual_html = manual[0]
 manual_md = manual[1]
 
-install_subdir(
-  manual_html.full_path(),
-  install_dir : datadir / 'doc/nix',
-)
-
 nix_nested_manpages = [
   [ 'nix-env',
     [
diff --git a/doc/manual/rl-next/ctrl-c-improved.md b/doc/manual/rl-next/ctrl-c-improved.md
new file mode 100644
index 000000000..c27a0edbb
--- /dev/null
+++ b/doc/manual/rl-next/ctrl-c-improved.md
@@ -0,0 +1,13 @@
+---
+synopsis: Ctrl-C stops Nix commands much more reliably and responsively
+issues: [7245, fj#393]
+cls: [2016]
+prs: [11618]
+category: Fixes
+credits: [roberth, 9999years]
+---
+
+CTRL-C will now stop Nix commands much more reliably and responsively. While
+there are still some cases where a Nix command can be slow or unresponsive
+following a `SIGINT` (please report these as issues!), the vast majority of
+signals will now cause the Nix command to quit quickly and consistently.
diff --git a/doc/manual/rl-next/fetchGit-regression.md b/doc/manual/rl-next/fetchGit-regression.md
new file mode 100644
index 000000000..f6b4fb9e5
--- /dev/null
+++ b/doc/manual/rl-next/fetchGit-regression.md
@@ -0,0 +1,23 @@
+---
+synopsis: restore backwards-compatibility of `builtins.fetchGit` with Nix 2.3
+issues: [5291, 5128]
+credits: [ma27]
+category: Fixes
+---
+
+Compatibility with `builtins.fetchGit` from Nix 2.3 has been restored as follows:
+
+* Until now, each `ref` was prefixed with `refs/heads` unless it starts with `refs/` itself.
+
+  Now, this is not done if the `ref` looks like a commit hash.
+
+* Specifying `builtins.fetchGit { ref = "a-tag"; /* … */ }` was broken because `refs/heads` was appended.
+
+  Now, the fetcher doesn't turn a ref into `refs/heads/ref`, but into `refs/*/ref`. That way,
+  the value in `ref` can be either a tag or a branch.
+
+* The ref resolution happens the same way as in git:
+
+  * If `refs/ref` exists, it's used.
+  * If a tag `refs/tags/ref` exists, it's used.
+  * If a branch `refs/heads/ref` exists, it's used.
diff --git a/doc/manual/rl-next/nix-fmt-default-argument.md b/doc/manual/rl-next/nix-fmt-default-argument.md
new file mode 100644
index 000000000..41b8f85bd
--- /dev/null
+++ b/doc/manual/rl-next/nix-fmt-default-argument.md
@@ -0,0 +1,38 @@
+---
+synopsis: Removing the `.` default argument passed to the `nix fmt` formatter
+issues: []
+prs: [11438]
+cls: [1902]
+category: Breaking Changes
+credits: zimbatm
+---
+
+The underlying formatter no longer receives the ". " default argument when `nix fmt` is called with no arguments.
+
+This change was necessary as the formatter wasn't able to distinguish between
+a user wanting to format the current folder with `nix fmt .` or the generic
+`nix fmt`.
+
+The default behaviour is now the responsibility of the formatter itself, and
+allows tools such as treefmt to format the whole tree instead of only the
+current directory and below.
+
+This may cause issues with some formatters: nixfmt, nixpkgs-fmt and alejandra currently format stdin when no arguments are passed.
+
+Here is a small wrapper example that will restore the previous behaviour for such a formatter:
+
+```nix
+{
+  outputs = { self, nixpkgs, systems }:
+    let
+      eachSystem = nixpkgs.lib.genAttrs (import systems) (system: nixpkgs.legacyPackages.${system});
+    in
+    {
+      formatter = eachSystem (pkgs:
+        pkgs.writeShellScriptBin "formatter" ''
+          if [[ $# = 0 ]]; set -- .; fi
+          exec "${pkgs.nixfmt-rfc-style}/bin/nixfmt "$@"
+        '');
+    };
+}
+```
diff --git a/doc/manual/rl-next/pytest-suite.md b/doc/manual/rl-next/pytest-suite.md
new file mode 100644
index 000000000..f4dbda1e8
--- /dev/null
+++ b/doc/manual/rl-next/pytest-suite.md
@@ -0,0 +1,10 @@
+---
+synopsis: "The beginnings of a new pytest-based functional test suite"
+category: Development
+cls: [2036, 2037]
+credits: jade
+---
+
+The existing integration/functional test suite is based on a large volume of shell scripts.
+This often makes it somewhat challenging to debug at the best of times.
+The goal of the pytest test suite is to make tests have more obvious dependencies on files and to make tests more concise and easier to write, as well as making new testing methods like snapshot testing easy.
diff --git a/doc/manual/rl-next/stack-traces.md b/doc/manual/rl-next/stack-traces.md
new file mode 100644
index 000000000..e16d6c886
--- /dev/null
+++ b/doc/manual/rl-next/stack-traces.md
@@ -0,0 +1,26 @@
+---
+synopsis: "Some Lix crashes now produce reporting instructions and a stack trace, then abort"
+cls: [1854]
+category: Improvements
+credits: jade
+---
+
+Lix, being a C++ program, can crash in a few kinds of ways.
+It can obviously do a memory access violation, which will generate a core dump and thus be relatively debuggable.
+But, worse, it could throw an unhandled exception, and, in the past, we would just show the message but not where it comes from, in spite of this always being a bug, since we expect all such errors to be translated to a Lix specific error.
+Now the latter kind of bug should print reporting instructions, a rudimentary stack trace and (depending on system configuration) generate a core dump.
+
+Sample output:
+
+```
+Lix crashed. This is a bug. We would appreciate if you report it along with what caused it at https://git.lix.systems/lix-project/lix/issues with the following information included:
+
+Exception: std::runtime_error: test exception
+Stack trace:
+ 0# nix::printStackTrace() in /home/jade/lix/lix3/build/src/nix/../libutil/liblixutil.so
+ 1# 0x000073C9862331F2 in /home/jade/lix/lix3/build/src/nix/../libmain/liblixmain.so
+ 2# 0x000073C985F2E21A in /nix/store/p44qan69linp3ii0xrviypsw2j4qdcp2-gcc-13.2.0-lib/lib/libstdc++.so.6
+ 3# 0x000073C985F2E285 in /nix/store/p44qan69linp3ii0xrviypsw2j4qdcp2-gcc-13.2.0-lib/lib/libstdc++.so.6
+ 4# nix::handleExceptions(std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> > const&, std::function<void ()>) in /home/jade/lix/lix3/build/src/nix/../libmain/liblixmain.so
+ ...
+```