From 6635a1cec98cdf5def038a50bdfd46217fee7118 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Thu, 21 Sep 2023 02:52:44 +0200
Subject: [PATCH 1/4] manual: Contributing -> Development, Hacking -> Building

what's currently called "hacking" are really instructions for setting up
a development environment and compiling from source. we have
a contribution guide in the repo (which rightly focuses on GitHub
workflows), and the material in the manual is more about working
on the code itself.

since we'd otherwise have three headings that amount to "Building Nix",
this change also moves the "classic Nix" instructions to the top.

we may want to reorganise this in the future, and bring
contributor-oriented information closer to the code, but for now let's
stick to more accurate names to ease navigation.
---
 README.md                                     |  3 +-
 doc/manual/src/SUMMARY.md.in                  | 16 ++--
 doc/manual/src/_redirects                     | 10 ++-
 .../hacking.md => development/building.md}    | 73 +++++++++----------
 .../cli-guideline.md                          |  0
 .../src/{contributing => development}/cxx.md  |  0
 .../documentation.md                          |  0
 .../experimental-features.md                  |  0
 .../{contributing => development}/index.md    |  0
 .../json-guideline.md                         |  0
 .../{contributing => development}/testing.md  |  0
 11 files changed, 54 insertions(+), 48 deletions(-)
 rename doc/manual/src/{contributing/hacking.md => development/building.md} (96%)
 rename doc/manual/src/{contributing => development}/cli-guideline.md (100%)
 rename doc/manual/src/{contributing => development}/cxx.md (100%)
 rename doc/manual/src/{contributing => development}/documentation.md (100%)
 rename doc/manual/src/{contributing => development}/experimental-features.md (100%)
 rename doc/manual/src/{contributing => development}/index.md (100%)
 rename doc/manual/src/{contributing => development}/json-guideline.md (100%)
 rename doc/manual/src/{contributing => development}/testing.md (100%)

diff --git a/README.md b/README.md
index e1cace3b4d5..a6a846f36ce 100644
--- a/README.md
+++ b/README.md
@@ -15,8 +15,7 @@ Full reference documentation can be found in the [Nix manual](https://nixos.org/
 
 ## Building And Developing
 
-See our [Hacking guide](https://nixos.org/manual/nix/unstable/contributing/hacking.html) in our manual for instruction on how to
- set up a development environment and build Nix from source.
+Follow instructions in the Nix reference manual to [set up a development environment and build Nix from source](https://nixos.org/manual/nix/unstable/contributing/hacking.html).
 
 ## Contributing
 
diff --git a/doc/manual/src/SUMMARY.md.in b/doc/manual/src/SUMMARY.md.in
index cb54a3822d1..169221d7db7 100644
--- a/doc/manual/src/SUMMARY.md.in
+++ b/doc/manual/src/SUMMARY.md.in
@@ -115,14 +115,14 @@
   - [Derivation "ATerm" file format](protocols/derivation-aterm.md)
 - [C API](c-api.md)
 - [Glossary](glossary.md)
-- [Contributing](contributing/index.md)
-  - [Hacking](contributing/hacking.md)
-  - [Testing](contributing/testing.md)
-  - [Documentation](contributing/documentation.md)
-  - [Experimental Features](contributing/experimental-features.md)
-  - [CLI guideline](contributing/cli-guideline.md)
-  - [JSON guideline](contributing/json-guideline.md)
-  - [C++ style guide](contributing/cxx.md)
+- [Development](development/index.md)
+  - [Building](development/building.md)
+  - [Testing](development/testing.md)
+  - [Documentation](development/documentation.md)
+  - [CLI guideline](development/cli-guideline.md)
+  - [JSON guideline](development/json-guideline.md)
+  - [C++ style guide](development/cxx.md)
+  - [Experimental Features](development/experimental-features.md)
 - [Releases](release-notes/index.md)
 {{#include ./SUMMARY-rl-next.md}}
   - [Release 2.23 (2024-06-03)](release-notes/rl-2.23.md)
diff --git a/doc/manual/src/_redirects b/doc/manual/src/_redirects
index a04a36f1e17..a347cf23e37 100644
--- a/doc/manual/src/_redirects
+++ b/doc/manual/src/_redirects
@@ -20,7 +20,15 @@
 
 /command-ref/command-ref /command-ref 301!
 
-/contributing/contributing /contributing 301!
+/contributing/contributing /development 301!
+/contributing /development 301!
+/contributing/hacking /development/building 301!
+/contributing/testing /development/testing 301!
+/contributing/documentation /development/documentation 301!
+/contributing/experimental-features /development/experimental-features 301!
+/contributing/cli-guideline /development/cli-guideline 301!
+/contributing/json-guideline /development/json-guideline 301!
+/contributing/cxx /development/cxx 301!
 
 /expressions/expression-language /language/ 301!
 /expressions/language-constructs /language/constructs 301!
diff --git a/doc/manual/src/contributing/hacking.md b/doc/manual/src/development/building.md
similarity index 96%
rename from doc/manual/src/contributing/hacking.md
rename to doc/manual/src/development/building.md
index 08ba84faa53..5db9f530936 100644
--- a/doc/manual/src/contributing/hacking.md
+++ b/doc/manual/src/development/building.md
@@ -1,112 +1,111 @@
-# Hacking
+# Building Nix
 
-This section provides some notes on how to hack on Nix. To get the
-latest version of Nix from GitHub:
+This section provides some notes on how to start hacking on Nix.
+To get the latest version of Nix from GitHub:
 
 ```console
 $ git clone https://github.com/NixOS/nix.git
 $ cd nix
 ```
 
-The following instructions assume you already have some version of Nix installed locally, so that you can use it to set up the development environment. If you don't have it installed, follow the [installation instructions].
-
-[installation instructions]: ../installation/index.md
-
-## Building Nix with flakes
-
-This section assumes you are using Nix with the [`flakes`] and [`nix-command`] experimental features enabled.
-See the [Building Nix](#building-nix) section for equivalent instructions using stable Nix interfaces.
+> **Note**
+>
+> The following instructions assume you already have some version of Nix installed locally, so that you can use it to set up the development environment.
+> If you don't have it installed, follow the [installation instructions](../installation/installation.md).
 
-[`flakes`]: @docroot@/contributing/experimental-features.md#xp-feature-flakes
-[`nix-command`]: @docroot@/contributing/experimental-features.md#xp-nix-command
 
 To build all dependencies and start a shell in which all environment variables are set up so that those dependencies can be found:
 
 ```console
-$ nix develop
+$ nix-shell
 ```
 
-This shell also adds `./outputs/bin/nix` to your `$PATH` so you can run `nix` immediately after building it.
-
 To get a shell with one of the other [supported compilation environments](#compilation-environments):
 
 ```console
-$ nix develop .#native-clangStdenvPackages
+$ nix-shell --attr devShells.x86_64-linux.native-clangStdenvPackages
 ```
 
 > **Note**
 >
-> Use `ccacheStdenv` to drastically improve rebuild time.
+> You can use `native-ccacheStdenvPackages` to drastically improve rebuild time.
 > By default, [ccache](https://ccache.dev) keeps artifacts in `~/.cache/ccache/`.
 
 To build Nix itself in this shell:
 
 ```console
 [nix-shell]$ autoreconfPhase
-[nix-shell]$ configurePhase
-[nix-shell]$ make -j $NIX_BUILD_CORES OPTIMIZE=0
+[nix-shell]$ ./configure $configureFlags --prefix=$(pwd)/outputs/out
+[nix-shell]$ make -j $NIX_BUILD_CORES
 ```
 
 To install it in `$(pwd)/outputs` and test it:
 
 ```console
-[nix-shell]$ make install OPTIMIZE=0
-[nix-shell]$ make installcheck check -j $NIX_BUILD_CORES
-[nix-shell]$ nix --version
+[nix-shell]$ make install
+[nix-shell]$ make installcheck -j $NIX_BUILD_CORES
+[nix-shell]$ ./outputs/out/bin/nix --version
 nix (Nix) 2.12
 ```
 
-For more information on running and filtering tests, see
-[`testing.md`](./testing.md).
-
 To build a release version of Nix for the current operating system and CPU architecture:
 
 ```console
-$ nix build
+$ nix-build
 ```
 
 You can also build Nix for one of the [supported platforms](#platforms).
 
-## Building Nix
+## Building Nix with flakes
+
+This section assumes you are using Nix with the [`flakes`] and [`nix-command`] experimental features enabled.
+
+[`flakes`]: @docroot@/contributing/experimental-features.md#xp-feature-flakes
+[`nix-command`]: @docroot@/contributing/experimental-features.md#xp-nix-command
 
 To build all dependencies and start a shell in which all environment variables are set up so that those dependencies can be found:
 
 ```console
-$ nix-shell
+$ nix develop
 ```
 
+This shell also adds `./outputs/bin/nix` to your `$PATH` so you can run `nix` immediately after building it.
+
 To get a shell with one of the other [supported compilation environments](#compilation-environments):
 
 ```console
-$ nix-shell --attr devShells.x86_64-linux.native-clangStdenvPackages
+$ nix develop .#native-clangStdenvPackages
 ```
 
 > **Note**
 >
-> You can use `native-ccacheStdenvPackages` to drastically improve rebuild time.
+> Use `ccacheStdenv` to drastically improve rebuild time.
 > By default, [ccache](https://ccache.dev) keeps artifacts in `~/.cache/ccache/`.
 
 To build Nix itself in this shell:
 
 ```console
 [nix-shell]$ autoreconfPhase
-[nix-shell]$ ./configure $configureFlags --prefix=$(pwd)/outputs/out
-[nix-shell]$ make -j $NIX_BUILD_CORES
+[nix-shell]$ configurePhase
+[nix-shell]$ make -j $NIX_BUILD_CORES OPTIMIZE=0
 ```
 
 To install it in `$(pwd)/outputs` and test it:
 
 ```console
-[nix-shell]$ make install
-[nix-shell]$ make installcheck -j $NIX_BUILD_CORES
-[nix-shell]$ ./outputs/out/bin/nix --version
+[nix-shell]$ make install OPTIMIZE=0
+[nix-shell]$ make installcheck check -j $NIX_BUILD_CORES
+[nix-shell]$ nix --version
 nix (Nix) 2.12
 ```
 
+For more information on running and filtering tests, see
+[`testing.md`](./testing.md).
+
 To build a release version of Nix for the current operating system and CPU architecture:
 
 ```console
-$ nix-build
+$ nix build
 ```
 
 You can also build Nix for one of the [supported platforms](#platforms).
diff --git a/doc/manual/src/contributing/cli-guideline.md b/doc/manual/src/development/cli-guideline.md
similarity index 100%
rename from doc/manual/src/contributing/cli-guideline.md
rename to doc/manual/src/development/cli-guideline.md
diff --git a/doc/manual/src/contributing/cxx.md b/doc/manual/src/development/cxx.md
similarity index 100%
rename from doc/manual/src/contributing/cxx.md
rename to doc/manual/src/development/cxx.md
diff --git a/doc/manual/src/contributing/documentation.md b/doc/manual/src/development/documentation.md
similarity index 100%
rename from doc/manual/src/contributing/documentation.md
rename to doc/manual/src/development/documentation.md
diff --git a/doc/manual/src/contributing/experimental-features.md b/doc/manual/src/development/experimental-features.md
similarity index 100%
rename from doc/manual/src/contributing/experimental-features.md
rename to doc/manual/src/development/experimental-features.md
diff --git a/doc/manual/src/contributing/index.md b/doc/manual/src/development/index.md
similarity index 100%
rename from doc/manual/src/contributing/index.md
rename to doc/manual/src/development/index.md
diff --git a/doc/manual/src/contributing/json-guideline.md b/doc/manual/src/development/json-guideline.md
similarity index 100%
rename from doc/manual/src/contributing/json-guideline.md
rename to doc/manual/src/development/json-guideline.md
diff --git a/doc/manual/src/contributing/testing.md b/doc/manual/src/development/testing.md
similarity index 100%
rename from doc/manual/src/contributing/testing.md
rename to doc/manual/src/development/testing.md

From 83c40c025d5a0d6ea9710a8942869a530bb43a55 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Tue, 11 Jun 2024 17:18:12 +0200
Subject: [PATCH 2/4] fix makefile

---
 doc/manual/local.mk | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/doc/manual/local.mk b/doc/manual/local.mk
index 71ad5c8e640..f149c50d069 100644
--- a/doc/manual/local.mk
+++ b/doc/manual/local.mk
@@ -95,7 +95,7 @@ $(d)/nix-profiles.5: $(d)/src/command-ref/files/profiles.md
 	$(trace-gen) lowdown -sT man --nroff-nolinks -M section=5 $^.tmp -o $@
 	@rm $^.tmp
 
-$(d)/src/SUMMARY.md: $(d)/src/SUMMARY.md.in $(d)/src/SUMMARY-rl-next.md $(d)/src/store/types $(d)/src/command-ref/new-cli $(d)/src/contributing/experimental-feature-descriptions.md
+$(d)/src/SUMMARY.md: $(d)/src/SUMMARY.md.in $(d)/src/SUMMARY-rl-next.md $(d)/src/store/types $(d)/src/command-ref/new-cli $(d)/src/development/experimental-feature-descriptions.md
 	@cp $< $@
 	@$(call process-includes,$@,$@)
 
@@ -124,7 +124,7 @@ $(d)/conf-file.json: $(doc_nix)
 	$(trace-gen) $(dummy-env) $(doc_nix) config show --json --experimental-features nix-command > $@.tmp
 	@mv $@.tmp $@
 
-$(d)/src/contributing/experimental-feature-descriptions.md: $(d)/xp-features.json $(d)/utils.nix $(d)/generate-xp-features.nix $(doc_nix)
+$(d)/src/development/experimental-feature-descriptions.md: $(d)/xp-features.json $(d)/utils.nix $(d)/generate-xp-features.nix $(doc_nix)
 	@rm -rf $@ $@.tmp
 	$(trace-gen) $(nix-eval) --write-to $@.tmp --expr 'import doc/manual/generate-xp-features.nix (builtins.fromJSON (builtins.readFile $<))'
 	@mv $@.tmp $@
@@ -213,11 +213,11 @@ doc/manual/generated/man1/nix3-manpages: $(d)/src/command-ref/new-cli
 	done
 	@touch $@
 
-# the `! -name 'contributing.md'` filter excludes the one place where
+# the `! -name 'documentation.md'` filter excludes the one place where
 # `@docroot@` is to be preserved for documenting the mechanism
 # FIXME: maybe contributing guides should live right next to the code
 # instead of in the manual
-$(docdir)/manual/index.html: $(MANUAL_SRCS) $(d)/book.toml $(d)/anchors.jq $(d)/custom.css $(d)/src/SUMMARY.md $(d)/src/store/types $(d)/src/command-ref/new-cli $(d)/src/contributing/experimental-feature-descriptions.md $(d)/src/command-ref/conf-file.md $(d)/src/language/builtins.md $(d)/src/language/builtin-constants.md $(d)/src/release-notes/rl-next.md $(d)/src/figures $(d)/src/favicon.png $(d)/src/favicon.svg
+$(docdir)/manual/index.html: $(MANUAL_SRCS) $(d)/book.toml $(d)/anchors.jq $(d)/custom.css $(d)/src/SUMMARY.md $(d)/src/store/types $(d)/src/command-ref/new-cli $(d)/src/development/experimental-feature-descriptions.md $(d)/src/command-ref/conf-file.md $(d)/src/language/builtins.md $(d)/src/language/builtin-constants.md $(d)/src/release-notes/rl-next.md $(d)/src/figures $(d)/src/favicon.png $(d)/src/favicon.svg
 	$(trace-gen) \
 		tmp="$$(mktemp -d)"; \
 		cp -r doc/manual "$$tmp"; \

From 83c08ab9ff8c37839822b32d99ae56da4bdd3a1a Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Tue, 11 Jun 2024 17:42:28 +0200
Subject: [PATCH 3/4] migrate all internal links

---
 CONTRIBUTING.md                               |  8 +-
 README.md                                     |  6 +-
 doc/manual/generate-builtins.nix              |  2 +-
 doc/manual/generate-settings.nix              |  4 +-
 doc/manual/generate-store-info.nix            |  4 +-
 doc/manual/generate-xp-features-shortlist.nix |  2 +-
 doc/manual/redirects.js                       |  9 +-
 doc/manual/src/SUMMARY.md.in                  |  1 +
 doc/manual/src/c-api.md                       |  2 +-
 .../src/command-ref/experimental-commands.md  |  2 +-
 .../src/command-ref/nix-store/realise.md      |  2 +-
 doc/manual/src/development/building.md        | 82 +------------------
 doc/manual/src/development/contributing.md    | 79 ++++++++++++++++++
 doc/manual/src/glossary.md                    |  4 +-
 .../src/installation/installing-binary.md     |  2 +-
 .../src/language/advanced-attributes.md       | 10 +--
 doc/manual/src/protocols/derivation-aterm.md  |  4 +-
 doc/manual/src/protocols/json/derivation.md   |  2 +-
 .../src/protocols/json/store-object-info.md   |  2 +-
 doc/manual/src/release-notes/rl-2.18.md       |  4 +-
 doc/manual/src/release-notes/rl-2.19.md       |  6 +-
 doc/manual/src/release-notes/rl-2.23.md       |  4 +-
 doc/manual/src/release-notes/rl-2.4.md        |  2 +-
 .../file-system-object/content-address.md     |  2 +-
 .../src/store/store-object/content-address.md |  2 +-
 src/libexpr/eval-settings.hh                  |  2 +-
 src/libexpr/primops/fetchTree.cc              | 10 +--
 src/libstore/globals.hh                       |  6 +-
 src/libutil/config.hh                         |  2 +-
 src/nix/nix.md                                |  6 +-
 30 files changed, 140 insertions(+), 133 deletions(-)
 create mode 100644 doc/manual/src/development/contributing.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 38f5d43b710..12423366a74 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -41,9 +41,9 @@ Check out the [security policy](https://github.com/NixOS/nix/security/policy).
    There are many open pull requests that might already do what you intend to work on.
    You can use [labels](https://github.com/NixOS/nix/labels) to filter for relevant topics.
 
-3. Check the [Nix reference manual](https://nixos.org/manual/nix/unstable/contributing/hacking.html) for information on building Nix and running its tests.
+3. Check the [Nix reference manual](https://nix.dev/manual/nix/development/development/building.html) for information on building Nix and running its tests.
 
-   For contributions to the command line interface, please check the [CLI guidelines](https://nixos.org/manual/nix/unstable/contributing/cli-guideline.html).
+   For contributions to the command line interface, please check the [CLI guidelines](https://nix.dev/manual/nix/development/development/cli-guideline.html).
 
 4. Make your change!
 
@@ -69,7 +69,7 @@ Check out the [security policy](https://github.com/NixOS/nix/security/policy).
    - [ ] API documentation in header files
    - [ ] Code and comments are self-explanatory
    - [ ] Commit message explains **why** the change was made
-   - [ ] New feature or incompatible change: [add a release note](https://nixos.org/manual/nix/stable/contributing/hacking#add-a-release-note)
+   - [ ] New feature or incompatible change: [add a release note](https://nix.dev/manual/nix/development/development/contributing.html#add-a-release-note)
 
 7. If you need additional feedback or help to getting pull request into shape, ask other contributors using [@mentions](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#mentioning-people-and-teams).
 
@@ -78,7 +78,7 @@ Check out the [security policy](https://github.com/NixOS/nix/security/policy).
 The Nix reference manual is hosted on https://nixos.org/manual/nix.
 The underlying source files are located in [`doc/manual/src`](./doc/manual/src).
 For small changes you can [use GitHub to edit these files](https://docs.github.com/en/repositories/working-with-files/managing-files/editing-files)
-For larger changes see the [Nix reference manual](https://nixos.org/manual/nix/unstable/contributing/hacking.html).
+For larger changes see the [Nix reference manual](https://nix.dev/manual/nix/development/development/contributing.html).
 
 ## Getting help
 
diff --git a/README.md b/README.md
index a6a846f36ce..5ccf8b190e2 100644
--- a/README.md
+++ b/README.md
@@ -4,18 +4,18 @@
 [![Test](https://github.com/NixOS/nix/workflows/Test/badge.svg)](https://github.com/NixOS/nix/actions)
 
 Nix is a powerful package manager for Linux and other Unix systems that makes package
-management reliable and reproducible. Please refer to the [Nix manual](https://nixos.org/nix/manual)
+management reliable and reproducible. Please refer to the [Nix manual](https://nix.dev/reference/nix-manual)
 for more details.
 
 ## Installation and first steps
 
 Visit [nix.dev](https://nix.dev) for [installation instructions](https://nix.dev/tutorials/install-nix) and [beginner tutorials](https://nix.dev/tutorials/first-steps).
 
-Full reference documentation can be found in the [Nix manual](https://nixos.org/nix/manual).
+Full reference documentation can be found in the [Nix manual](https://nix.dev/reference/nix-manual).
 
 ## Building And Developing
 
-Follow instructions in the Nix reference manual to [set up a development environment and build Nix from source](https://nixos.org/manual/nix/unstable/contributing/hacking.html).
+Follow instructions in the Nix reference manual to [set up a development environment and build Nix from source](https://nix.dev/manual/nix/development/development/building.html).
 
 ## Contributing
 
diff --git a/doc/manual/generate-builtins.nix b/doc/manual/generate-builtins.nix
index 007b698f1bf..b3f75efefe2 100644
--- a/doc/manual/generate-builtins.nix
+++ b/doc/manual/generate-builtins.nix
@@ -10,7 +10,7 @@ let
       experimentalNotice = optionalString (experimental-feature != null) ''
         > **Note**
         >
-        > This function is only available if the [`${experimental-feature}` experimental feature](@docroot@/contributing/experimental-features.md#xp-feature-${experimental-feature}) is enabled.
+        > This function is only available if the [`${experimental-feature}` experimental feature](@docroot@/development/experimental-features.md#xp-feature-${experimental-feature}) is enabled.
         >
         > For example, include the following in [`nix.conf`](@docroot@/command-ref/conf-file.md):
         >
diff --git a/doc/manual/generate-settings.nix b/doc/manual/generate-settings.nix
index 504cda3621e..93a8e093e48 100644
--- a/doc/manual/generate-settings.nix
+++ b/doc/manual/generate-settings.nix
@@ -33,10 +33,10 @@ let
           > **Warning**
           >
           > This setting is part of an
-          > [experimental feature](@docroot@/contributing/experimental-features.md).
+          > [experimental feature](@docroot@/development/experimental-features.md).
           >
           > To change this setting, make sure the
-          > [`${experimentalFeature}` experimental feature](@docroot@/contributing/experimental-features.md#xp-feature-${experimentalFeature})
+          > [`${experimentalFeature}` experimental feature](@docroot@/development/experimental-features.md#xp-feature-${experimentalFeature})
           > is enabled.
           > For example, include the following in [`nix.conf`](@docroot@/command-ref/conf-file.md):
           >
diff --git a/doc/manual/generate-store-info.nix b/doc/manual/generate-store-info.nix
index c311c3c3934..cc370412414 100644
--- a/doc/manual/generate-store-info.nix
+++ b/doc/manual/generate-store-info.nix
@@ -32,10 +32,10 @@ let
         > **Warning**
         >
         > This store is part of an
-        > [experimental feature](@docroot@/contributing/experimental-features.md).
+        > [experimental feature](@docroot@/development/experimental-features.md).
         >
         > To use this store, make sure the
-        > [`${experimentalFeature}` experimental feature](@docroot@/contributing/experimental-features.md#xp-feature-${experimentalFeature})
+        > [`${experimentalFeature}` experimental feature](@docroot@/development/experimental-features.md#xp-feature-${experimentalFeature})
         > is enabled.
         > For example, include the following in [`nix.conf`](@docroot@/command-ref/conf-file.md):
         >
diff --git a/doc/manual/generate-xp-features-shortlist.nix b/doc/manual/generate-xp-features-shortlist.nix
index ec09f4b75f7..eb735ba5f7a 100644
--- a/doc/manual/generate-xp-features-shortlist.nix
+++ b/doc/manual/generate-xp-features-shortlist.nix
@@ -4,6 +4,6 @@ with import <nix/utils.nix>;
 let
   showExperimentalFeature = name: doc:
     ''
-      - [`${name}`](@docroot@/contributing/experimental-features.md#xp-feature-${name})
+      - [`${name}`](@docroot@/development/experimental-features.md#xp-feature-${name})
     '';
 in xps: indent "  " (concatStrings (attrValues (mapAttrs showExperimentalFeature xps)))
diff --git a/doc/manual/redirects.js b/doc/manual/redirects.js
index 633932e5549..bd99fe57b8d 100644
--- a/doc/manual/redirects.js
+++ b/doc/manual/redirects.js
@@ -346,7 +346,7 @@ const redirects = {
     "macos": "uninstall.html#macos",
     "uninstalling": "uninstall.html",
   },
-  "contributing/hacking.html": {
+  "development/building.html": {
     "nix-with-flakes": "#building-nix-with-flakes",
     "classic-nix": "#building-nix",
     "running-tests": "testing.html#running-tests",
@@ -357,7 +357,12 @@ const redirects = {
     "installer-tests": "testing.html#installer-tests",
     "one-time-setup": "testing.html#one-time-setup",
     "using-the-ci-generated-installer-for-manual-testing": "testing.html#using-the-ci-generated-installer-for-manual-testing",
-    "characterization-testing": "#characterisation-testing-unit",
+    "characterization-testing": "testing.html#characterisation-testing-unit",
+    "add-a-release-note": "contributing.html#add-a-release-note",
+    "add-an-entry": "contributing.html#add-an-entry",
+    "build-process": "contributing.html#build-process",
+    "reverting": "contributing.html#reverting",
+    "branches": "contributing.html#branches",
   },
   "glossary.html": {
     "gloss-local-store": "store/types/local-store.html",
diff --git a/doc/manual/src/SUMMARY.md.in b/doc/manual/src/SUMMARY.md.in
index 169221d7db7..178e45d51b3 100644
--- a/doc/manual/src/SUMMARY.md.in
+++ b/doc/manual/src/SUMMARY.md.in
@@ -123,6 +123,7 @@
   - [JSON guideline](development/json-guideline.md)
   - [C++ style guide](development/cxx.md)
   - [Experimental Features](development/experimental-features.md)
+  - [Contributing](development/contributing.md)
 - [Releases](release-notes/index.md)
 {{#include ./SUMMARY-rl-next.md}}
   - [Release 2.23 (2024-06-03)](release-notes/rl-2.23.md)
diff --git a/doc/manual/src/c-api.md b/doc/manual/src/c-api.md
index 29df0b64419..0cdd8383231 100644
--- a/doc/manual/src/c-api.md
+++ b/doc/manual/src/c-api.md
@@ -10,7 +10,7 @@ See:
 - [Matrix Room *Nix Bindings*](https://matrix.to/#/#nix-bindings:nixos.org) for discussion and questions.
 - [Stabilisation Milestone](https://github.com/NixOS/nix/milestone/52)
 - [Other C API PRs and issues](https://github.com/NixOS/nix/labels/c%20api)
-- [Contributing C API Documentation](contributing/documentation.md#c-api-documentation), including how to build it locally.
+- [Contributing C API Documentation](development/documentation.md#c-api-documentation), including how to build it locally.
 
 [Getting Started]: https://hydra.nixos.org/job/nix/master/external-api-docs/latest/download-by-type/doc/external-api-docs
 [Index]: https://hydra.nixos.org/job/nix/master/external-api-docs/latest/download-by-type/doc/external-api-docs/globals.html
diff --git a/doc/manual/src/command-ref/experimental-commands.md b/doc/manual/src/command-ref/experimental-commands.md
index 286ddc6d634..1190729a230 100644
--- a/doc/manual/src/command-ref/experimental-commands.md
+++ b/doc/manual/src/command-ref/experimental-commands.md
@@ -1,6 +1,6 @@
 # Experimental Commands
 
-This section lists [experimental commands](@docroot@/contributing/experimental-features.md#xp-feature-nix-command).
+This section lists [experimental commands](@docroot@/development/experimental-features.md#xp-feature-nix-command).
 
 > **Warning**
 >
diff --git a/doc/manual/src/command-ref/nix-store/realise.md b/doc/manual/src/command-ref/nix-store/realise.md
index 6e56387ebdb..6ad20839301 100644
--- a/doc/manual/src/command-ref/nix-store/realise.md
+++ b/doc/manual/src/command-ref/nix-store/realise.md
@@ -32,7 +32,7 @@ If no substitutes are available and no store derivation is given, realisation fa
 [store objects]: @docroot@/store/store-object.md
 [closure]: @docroot@/glossary.md#gloss-closure
 [substituters]: @docroot@/command-ref/conf-file.md#conf-substituters
-[content-addressed derivations]: @docroot@/contributing/experimental-features.md#xp-feature-ca-derivations
+[content-addressed derivations]: @docroot@/development/experimental-features.md#xp-feature-ca-derivations
 [Nix database]: @docroot@/glossary.md#gloss-nix-database
 
 The resulting paths are printed on standard output.
diff --git a/doc/manual/src/development/building.md b/doc/manual/src/development/building.md
index 5db9f530936..06482afe79a 100644
--- a/doc/manual/src/development/building.md
+++ b/doc/manual/src/development/building.md
@@ -60,8 +60,8 @@ You can also build Nix for one of the [supported platforms](#platforms).
 
 This section assumes you are using Nix with the [`flakes`] and [`nix-command`] experimental features enabled.
 
-[`flakes`]: @docroot@/contributing/experimental-features.md#xp-feature-flakes
-[`nix-command`]: @docroot@/contributing/experimental-features.md#xp-nix-command
+[`flakes`]: @docroot@/development/experimental-features.md#xp-feature-flakes
+[`nix-command`]: @docroot@/development/experimental-features.md#xp-nix-command
 
 To build all dependencies and start a shell in which all environment variables are set up so that those dependencies can be found:
 
@@ -294,81 +294,3 @@ If it fails, run `git add --patch` to approve the suggestions _and commit again_
 To refresh pre-commit hook's config file, do the following:
 1. Exit the development shell and start it again by running `nix develop`.
 2. If you also use the pre-commit hook, also run `pre-commit-hooks-install` again.
-
-## Add a release note
-
-`doc/manual/rl-next` contains release notes entries for all unreleased changes.
-
-User-visible changes should come with a release note.
-
-### Add an entry
-
-Here's what a complete entry looks like. The file name is not incorporated in the document.
-
-```
----
-synopsis: Basically a title
-issues: 1234
-prs: 1238
----
-
-Here's one or more paragraphs that describe the change.
-
-- It's markdown
-- Add references to the manual using @docroot@
-```
-
-Significant changes should add the following header, which moves them to the top.
-
-```
-significance: significant
-```
-
-<!-- Keep an eye on https://codeberg.org/fgaz/changelog-d/issues/1 -->
-See also the [format documentation](https://github.com/haskell/cabal/blob/master/CONTRIBUTING.md#changelog).
-
-### Build process
-
-Releases have a precomputed `rl-MAJOR.MINOR.md`, and no `rl-next.md`.
-
-## Branches
-
-- [`master`](https://github.com/NixOS/nix/commits/master)
-
-  The main development branch. All changes are approved and merged here.
-  When developing a change, create a branch based on the latest `master`.
-
-  Maintainers try to [keep it in a release-worthy state](#reverting).
-
-- [`maintenance-*.*`](https://github.com/NixOS/nix/branches/all?query=maintenance)
-
-  These branches are the subject of backports only, and are
-  also [kept](#reverting) in a release-worthy state.
-
-  See [`maintainers/backporting.md`](https://github.com/NixOS/nix/blob/master/maintainers/backporting.md)
-
-- [`latest-release`](https://github.com/NixOS/nix/tree/latest-release)
-
-  The latest patch release of the latest minor version.
-
-  See [`maintainers/release-process.md`](https://github.com/NixOS/nix/blob/master/maintainers/release-process.md)
-
-- [`backport-*-to-*`](https://github.com/NixOS/nix/branches/all?query=backport)
-
-  Generally branches created by the backport action.
-
-  See [`maintainers/backporting.md`](https://github.com/NixOS/nix/blob/master/maintainers/backporting.md)
-
-- [_other_](https://github.com/NixOS/nix/branches/all)
-
-  Branches that do not conform to the above patterns should be feature branches.
-
-## Reverting
-
-If a change turns out to be merged by mistake, or contain a regression, it may be reverted.
-A revert is not a rejection of the contribution, but merely part of an effective development process.
-It makes sure that development keeps running smoothly, with minimal uncertainty, and less overhead.
-If maintainers have to worry too much about avoiding reverts, they would not be able to merge as much.
-By embracing reverts as a good part of the development process, everyone wins.
-
-However, taking a step back may be frustrating, so maintainers will be extra supportive on the next try.
diff --git a/doc/manual/src/development/contributing.md b/doc/manual/src/development/contributing.md
new file mode 100644
index 00000000000..7de7489dcb7
--- /dev/null
+++ b/doc/manual/src/development/contributing.md
@@ -0,0 +1,79 @@
+# Contributing
+
+## Add a release note
+
+`doc/manual/rl-next` contains release notes entries for all unreleased changes.
+
+User-visible changes should come with a release note.
+
+### Add an entry
+
+Here's what a complete entry looks like. The file name is not incorporated in the document.
+
+```
+---
+synopsis: Basically a title
+issues: 1234
+prs: 1238
+---
+
+Here's one or more paragraphs that describe the change.
+
+- It's markdown
+- Add references to the manual using @docroot@
+```
+
+Significant changes should add the following header, which moves them to the top.
+
+```
+significance: significant
+```
+
+<!-- Keep an eye on https://codeberg.org/fgaz/changelog-d/issues/1 -->
+See also the [format documentation](https://github.com/haskell/cabal/blob/master/CONTRIBUTING.md#changelog).
+
+### Build process
+
+Releases have a precomputed `rl-MAJOR.MINOR.md`, and no `rl-next.md`.
+
+## Branches
+
+- [`master`](https://github.com/NixOS/nix/commits/master)
+
+  The main development branch. All changes are approved and merged here.
+  When developing a change, create a branch based on the latest `master`.
+
+  Maintainers try to [keep it in a release-worthy state](#reverting).
+
+- [`maintenance-*.*`](https://github.com/NixOS/nix/branches/all?query=maintenance)
+
+  These branches are the subject of backports only, and are
+  also [kept](#reverting) in a release-worthy state.
+
+  See [`maintainers/backporting.md`](https://github.com/NixOS/nix/blob/master/maintainers/backporting.md)
+
+- [`latest-release`](https://github.com/NixOS/nix/tree/latest-release)
+
+  The latest patch release of the latest minor version.
+
+  See [`maintainers/release-process.md`](https://github.com/NixOS/nix/blob/master/maintainers/release-process.md)
+
+- [`backport-*-to-*`](https://github.com/NixOS/nix/branches/all?query=backport)
+
+  Generally branches created by the backport action.
+
+  See [`maintainers/backporting.md`](https://github.com/NixOS/nix/blob/master/maintainers/backporting.md)
+
+- [_other_](https://github.com/NixOS/nix/branches/all)
+
+  Branches that do not conform to the above patterns should be feature branches.
+
+## Reverting
+
+If a change turns out to be merged by mistake, or contain a regression, it may be reverted.
+A revert is not a rejection of the contribution, but merely part of an effective development process.
+It makes sure that development keeps running smoothly, with minimal uncertainty, and less overhead.
+If maintainers have to worry too much about avoiding reverts, they would not be able to merge as much.
+By embracing reverts as a good part of the development process, everyone wins.
+
+However, taking a step back may be frustrating, so maintainers will be extra supportive on the next try.
diff --git a/doc/manual/src/glossary.md b/doc/manual/src/glossary.md
index 4c9b2c52e51..85e8a435b31 100644
--- a/doc/manual/src/glossary.md
+++ b/doc/manual/src/glossary.md
@@ -168,7 +168,7 @@
 
 - [impure derivation]{#gloss-impure-derivation}
 
-  [An experimental feature](#@docroot@/contributing/experimental-features.md#xp-feature-impure-derivations) that allows derivations to be explicitly marked as impure,
+  [An experimental feature](#@docroot@/development/experimental-features.md#xp-feature-impure-derivations) that allows derivations to be explicitly marked as impure,
   so that they are always rebuilt, and their outputs not reused by subsequent calls to realise them.
 
 - [Nix database]{#gloss-nix-database}
@@ -353,7 +353,7 @@
   Not yet stabilized functionality guarded by named experimental feature flags.
   These flags are enabled or disabled with the [`experimental-features`](./command-ref/conf-file.html#conf-experimental-features) setting.
 
-  See the contribution guide on the [purpose and lifecycle of experimental feaures](@docroot@/contributing/experimental-features.md).
+  See the contribution guide on the [purpose and lifecycle of experimental feaures](@docroot@/development/experimental-features.md).
 
 
 [Nix language]: ./language/index.md
diff --git a/doc/manual/src/installation/installing-binary.md b/doc/manual/src/installation/installing-binary.md
index 385008d8c16..6a168ff3dfd 100644
--- a/doc/manual/src/installation/installing-binary.md
+++ b/doc/manual/src/installation/installing-binary.md
@@ -77,7 +77,7 @@ $ su root
 # Installing from a binary tarball
 
 You can also download a binary tarball that contains Nix and all its dependencies:
-- Choose a [version](https://releases.nixos.org/?prefix=nix/) and [system type](../contributing/hacking.md#platforms)
+- Choose a [version](https://releases.nixos.org/?prefix=nix/) and [system type](../development/building.md#platforms)
 - Download and unpack the tarball
 - Run the installer
 
diff --git a/doc/manual/src/language/advanced-attributes.md b/doc/manual/src/language/advanced-attributes.md
index 70ec06f5793..d40d29292d9 100644
--- a/doc/manual/src/language/advanced-attributes.md
+++ b/doc/manual/src/language/advanced-attributes.md
@@ -113,7 +113,7 @@ Derivations can declare some infrequently used optional attributes.
     > `nix-build`.
 
     If the [`configurable-impure-env` experimental
-    feature](@docroot@/contributing/experimental-features.md#xp-feature-configurable-impure-env)
+    feature](@docroot@/development/experimental-features.md#xp-feature-configurable-impure-env)
     is enabled, these environment variables can also be controlled
     through the
     [`impure-env`](@docroot@/command-ref/conf-file.md#conf-impure-env)
@@ -226,7 +226,7 @@ Derivations can declare some infrequently used optional attributes.
   - [`__contentAddressed`]{#adv-attr-__contentAddressed}
 
     > **Warning**
-    > This attribute is part of an [experimental feature](@docroot@/contributing/experimental-features.md).
+    > This attribute is part of an [experimental feature](@docroot@/development/experimental-features.md).
     >
     > To use this attribute, you must enable the
     > [`ca-derivations`][xp-feature-ca-derivations] experimental feature.
@@ -364,6 +364,6 @@ Derivations can declare some infrequently used optional attributes.
 
   ensures that the derivation can only be built on a machine with the `kvm` feature.
 
-[xp-feature-ca-derivations]: @docroot@/contributing/experimental-features.md#xp-feature-ca-derivations
-[xp-feature-dynamic-derivations]: @docroot@/contributing/experimental-features.md#xp-feature-dynamic-derivations
-[xp-feature-git-hashing]: @docroot@/contributing/experimental-features.md#xp-feature-git-hashing
+[xp-feature-ca-derivations]: @docroot@/development/experimental-features.md#xp-feature-ca-derivations
+[xp-feature-dynamic-derivations]: @docroot@/development/experimental-features.md#xp-feature-dynamic-derivations
+[xp-feature-git-hashing]: @docroot@/development/experimental-features.md#xp-feature-git-hashing
diff --git a/doc/manual/src/protocols/derivation-aterm.md b/doc/manual/src/protocols/derivation-aterm.md
index e58b602a349..1ba757ae024 100644
--- a/doc/manual/src/protocols/derivation-aterm.md
+++ b/doc/manual/src/protocols/derivation-aterm.md
@@ -14,6 +14,6 @@ Derivations are serialised in one of the following formats:
   DrvWithVersion(<version-string>, ...)
   ```
 
-  The only `version-string`s that are in use today are for [experimental features](@docroot@/contributing/experimental-features.md):
+  The only `version-string`s that are in use today are for [experimental features](@docroot@/development/experimental-features.md):
 
-  - `"xp-dyn-drv"` for the [`dynamic-derivations`](@docroot@/contributing/experimental-features.md#xp-feature-dynamic-derivations) experimental feature.
+  - `"xp-dyn-drv"` for the [`dynamic-derivations`](@docroot@/development/experimental-features.md#xp-feature-dynamic-derivations) experimental feature.
diff --git a/doc/manual/src/protocols/json/derivation.md b/doc/manual/src/protocols/json/derivation.md
index f881dd70381..2f85340d6c5 100644
--- a/doc/manual/src/protocols/json/derivation.md
+++ b/doc/manual/src/protocols/json/derivation.md
@@ -3,7 +3,7 @@
 > **Warning**
 >
 > This JSON format is currently
-> [**experimental**](@docroot@/contributing/experimental-features.md#xp-feature-nix-command)
+> [**experimental**](@docroot@/development/experimental-features.md#xp-feature-nix-command)
 > and subject to change.
 
 The JSON serialization of a
diff --git a/doc/manual/src/protocols/json/store-object-info.md b/doc/manual/src/protocols/json/store-object-info.md
index 9f647a96c24..6b4f4843711 100644
--- a/doc/manual/src/protocols/json/store-object-info.md
+++ b/doc/manual/src/protocols/json/store-object-info.md
@@ -3,7 +3,7 @@
 > **Warning**
 >
 > This JSON format is currently
-> [**experimental**](@docroot@/contributing/experimental-features.md#xp-feature-nix-command)
+> [**experimental**](@docroot@/development/experimental-features.md#xp-feature-nix-command)
 > and subject to change.
 
 Info about a [store object].
diff --git a/doc/manual/src/release-notes/rl-2.18.md b/doc/manual/src/release-notes/rl-2.18.md
index 4bbc52b508f..eb26fc9e721 100644
--- a/doc/manual/src/release-notes/rl-2.18.md
+++ b/doc/manual/src/release-notes/rl-2.18.md
@@ -13,7 +13,7 @@
 
 - The `discard-references` feature has been stabilized.
   This means that the
-  [unsafeDiscardReferences](@docroot@/contributing/experimental-features.md#xp-feature-discard-references)
+  [unsafeDiscardReferences](@docroot@/development/experimental-features.md#xp-feature-discard-references)
   attribute is no longer guarded by an experimental flag and can be used
   freely.
 
@@ -21,7 +21,7 @@
   This only affects `nix-build --json` when "building" non-derivation things like fetched sources, which is a no-op.
 
 - A new builtin [`outputOf`](@docroot@/language/builtins.md#builtins-outputOf) has been added.
-  It is part of the [`dynamic-derivations`](@docroot@/contributing/experimental-features.md#xp-feature-dynamic-derivations) experimental feature.
+  It is part of the [`dynamic-derivations`](@docroot@/development/experimental-features.md#xp-feature-dynamic-derivations) experimental feature.
 
 - Flake follow paths at depths greater than 2 are now handled correctly, preventing "follows a non-existent input" errors.
 
diff --git a/doc/manual/src/release-notes/rl-2.19.md b/doc/manual/src/release-notes/rl-2.19.md
index ba6eb9c64a4..e2e2f85cc3c 100644
--- a/doc/manual/src/release-notes/rl-2.19.md
+++ b/doc/manual/src/release-notes/rl-2.19.md
@@ -17,8 +17,8 @@
 
 - `nix-shell` shebang lines now support single-quoted arguments.
 
-- `builtins.fetchTree` is now its own experimental feature, [`fetch-tree`](@docroot@/contributing/experimental-features.md#xp-fetch-tree).
-  This allows stabilising it independently of the rest of what is encompassed by [`flakes`](@docroot@/contributing/experimental-features.md#xp-fetch-tree).
+- `builtins.fetchTree` is now its own experimental feature, [`fetch-tree`](@docroot@/development/experimental-features.md#xp-fetch-tree).
+  This allows stabilising it independently of the rest of what is encompassed by [`flakes`](@docroot@/development/experimental-features.md#xp-fetch-tree).
 
 - The interface for creating and updating lock files has been overhauled:
 
@@ -33,7 +33,7 @@
   - The flake-specific flags `--recreate-lock-file` and `--update-input` have been removed from all commands operating on installables.
     They are superceded by `nix flake update`.
 
-- Commit signature verification for the [`builtins.fetchGit`](@docroot@/language/builtins.md#builtins-fetchGit) is added as the new [`verified-fetches` experimental feature](@docroot@/contributing/experimental-features.md#xp-feature-verified-fetches).
+- Commit signature verification for the [`builtins.fetchGit`](@docroot@/language/builtins.md#builtins-fetchGit) is added as the new [`verified-fetches` experimental feature](@docroot@/development/experimental-features.md#xp-feature-verified-fetches).
 
 - [`nix path-info --json`](@docroot@/command-ref/new-cli/nix3-path-info.md)
   (experimental) now returns a JSON map rather than JSON list.
diff --git a/doc/manual/src/release-notes/rl-2.23.md b/doc/manual/src/release-notes/rl-2.23.md
index 3c59b85838f..ac842fdc058 100644
--- a/doc/manual/src/release-notes/rl-2.23.md
+++ b/doc/manual/src/release-notes/rl-2.23.md
@@ -14,7 +14,7 @@
 
 - Modify `nix derivation {add,show}` JSON format [#9866](https://github.com/NixOS/nix/issues/9866) [#10722](https://github.com/NixOS/nix/pull/10722)
 
-  The JSON format for derivations has been slightly revised to better conform to our [JSON guidelines](@docroot@/contributing/cli-guideline.md#returning-future-proof-json).
+  The JSON format for derivations has been slightly revised to better conform to our [JSON guidelines](@docroot@/development/cli-guideline.md#returning-future-proof-json).
   In particular, the hash algorithm and content addressing method of content-addresed derivation outputs are now separated into two fields `hashAlgo` and `method`,
   rather than one field with an arcane `:`-separated format.
 
@@ -89,7 +89,7 @@
   This makes records of this sort more self-describing, and easier to consume programmatically.
 
   We will follow this design principle going forward;
-  the [JSON guidelines](@docroot@/contributing/json-guideline.md) in the contributing section have been updated accordingly.
+  the [JSON guidelines](@docroot@/development/json-guideline.md) in the contributing section have been updated accordingly.
 
 - Large path warnings [#10661](https://github.com/NixOS/nix/pull/10661)
 
diff --git a/doc/manual/src/release-notes/rl-2.4.md b/doc/manual/src/release-notes/rl-2.4.md
index 8b566fc7b93..1201e53b6ae 100644
--- a/doc/manual/src/release-notes/rl-2.4.md
+++ b/doc/manual/src/release-notes/rl-2.4.md
@@ -23,7 +23,7 @@ more than 2800 commits from 195 contributors since release 2.3.
 * The **`nix` command** has seen a lot of work and is now almost at
   feature parity with the old command-line interface (the `nix-*`
   commands). It aims to be [more modern, consistent and pleasant to
-  use](../contributing/cli-guideline.md) than the old CLI. It is still
+  use](../development/cli-guideline.md) than the old CLI. It is still
   marked as experimental but its interface should not change much
   anymore in future releases.
 
diff --git a/doc/manual/src/store/file-system-object/content-address.md b/doc/manual/src/store/file-system-object/content-address.md
index 1c63c52ebda..410d7fb7c7c 100644
--- a/doc/manual/src/store/file-system-object/content-address.md
+++ b/doc/manual/src/store/file-system-object/content-address.md
@@ -82,4 +82,4 @@ In the future, we may support a Git-like hash for such file system objects, or w
 
 [file system object]: ../file-system-object.md
 [store object]: ../store-object.md
-[xp-feature-git-hashing]: @docroot@/contributing/experimental-features.md#xp-feature-git-hashing
+[xp-feature-git-hashing]: @docroot@/development/experimental-features.md#xp-feature-git-hashing
diff --git a/doc/manual/src/store/store-object/content-address.md b/doc/manual/src/store/store-object/content-address.md
index f6f982035ef..02dce283650 100644
--- a/doc/manual/src/store/store-object/content-address.md
+++ b/doc/manual/src/store/store-object/content-address.md
@@ -92,4 +92,4 @@ becomes more widespread, this restriction will be revisited.
 
 [fso-ca]: ../file-system-object/content-address.md
 [sp-spec]: @docroot@/protocols/store-path.md
-[xp-feature-git-hashing]: @docroot@/contributing/experimental-features.md#xp-feature-git-hashing
+[xp-feature-git-hashing]: @docroot@/development/experimental-features.md#xp-feature-git-hashing
diff --git a/src/libexpr/eval-settings.hh b/src/libexpr/eval-settings.hh
index d01de980fa4..60dd192268b 100644
--- a/src/libexpr/eval-settings.hh
+++ b/src/libexpr/eval-settings.hh
@@ -27,7 +27,7 @@ struct EvalSettings : Config
           extern "C" typedef void (*ValueInitialiser) (EvalState & state, Value & v);
           ```
 
-          The [Nix C++ API documentation](@docroot@/contributing/documentation.md#api-documentation) has more details on evaluator internals.
+          The [Nix C++ API documentation](@docroot@/development/documentation.md#api-documentation) has more details on evaluator internals.
 
         - `builtins.exec` *arguments*
 
diff --git a/src/libexpr/primops/fetchTree.cc b/src/libexpr/primops/fetchTree.cc
index a99a715770b..d4a653e05d7 100644
--- a/src/libexpr/primops/fetchTree.cc
+++ b/src/libexpr/primops/fetchTree.cc
@@ -383,7 +383,7 @@ static RegisterPrimOp primop_fetchTree({
       - `"mercurial"`
 
      *input* can also be a [URL-like reference](@docroot@/command-ref/new-cli/nix3-flake.md#flake-references).
-     The additional input types and the URL-like syntax requires the [`flakes` experimental feature](@docroot@/contributing/experimental-features.md#xp-feature-flakes) to be enabled.
+     The additional input types and the URL-like syntax requires the [`flakes` experimental feature](@docroot@/development/experimental-features.md#xp-feature-flakes) to be enabled.
 
       > **Example**
       >
@@ -642,12 +642,12 @@ static RegisterPrimOp primop_fetchGit({
 
         Whether to check `rev` for a signature matching `publicKey` or `publicKeys`.
         If `verifyCommit` is enabled, then `fetchGit` cannot use a local repository with uncommitted changes.
-        Requires the [`verified-fetches` experimental feature](@docroot@/contributing/experimental-features.md#xp-feature-verified-fetches).
+        Requires the [`verified-fetches` experimental feature](@docroot@/development/experimental-features.md#xp-feature-verified-fetches).
 
       - `publicKey`
 
         The public key against which `rev` is verified if `verifyCommit` is enabled.
-        Requires the [`verified-fetches` experimental feature](@docroot@/contributing/experimental-features.md#xp-feature-verified-fetches).
+        Requires the [`verified-fetches` experimental feature](@docroot@/development/experimental-features.md#xp-feature-verified-fetches).
 
       - `keytype` (default: `"ssh-ed25519"`)
 
@@ -659,7 +659,7 @@ static RegisterPrimOp primop_fetchGit({
         - `"ssh-ed25519"`
         - `"ssh-ed25519-sk"`
         - `"ssh-rsa"`
-        Requires the [`verified-fetches` experimental feature](@docroot@/contributing/experimental-features.md#xp-feature-verified-fetches).
+        Requires the [`verified-fetches` experimental feature](@docroot@/development/experimental-features.md#xp-feature-verified-fetches).
 
       - `publicKeys`
 
@@ -673,7 +673,7 @@ static RegisterPrimOp primop_fetchGit({
         }
         ```
 
-        Requires the [`verified-fetches` experimental feature](@docroot@/contributing/experimental-features.md#xp-feature-verified-fetches).
+        Requires the [`verified-fetches` experimental feature](@docroot@/development/experimental-features.md#xp-feature-verified-fetches).
 
 
       Here are some examples of how to use `fetchGit`.
diff --git a/src/libstore/globals.hh b/src/libstore/globals.hh
index 843e77bcf5f..39703270068 100644
--- a/src/libstore/globals.hh
+++ b/src/libstore/globals.hh
@@ -303,7 +303,7 @@ public:
              For backward compatibility, `ssh://` may be omitted.
              The hostname may be an alias defined in `~/.ssh/config`.
 
-          2. A comma-separated list of [Nix system types](@docroot@/contributing/hacking.md#system-type).
+          2. A comma-separated list of [Nix system types](@docroot@/development/hacking.md#system-type).
              If omitted, this defaults to the local platform type.
 
              > **Example**
@@ -883,13 +883,13 @@ public:
 
           - `ca-derivations`
 
-            Included by default if the [`ca-derivations` experimental feature](@docroot@/contributing/experimental-features.md#xp-feature-ca-derivations) is enabled.
+            Included by default if the [`ca-derivations` experimental feature](@docroot@/development/experimental-features.md#xp-feature-ca-derivations) is enabled.
 
             This system feature is implicitly required by derivations with the [`__contentAddressed` attribute](@docroot@/language/advanced-attributes.md#adv-attr-__contentAddressed).
 
           - `recursive-nix`
 
-            Included by default if the [`recursive-nix` experimental feature](@docroot@/contributing/experimental-features.md#xp-feature-recursive-nix) is enabled.
+            Included by default if the [`recursive-nix` experimental feature](@docroot@/development/experimental-features.md#xp-feature-recursive-nix) is enabled.
 
           - `uid-range`
 
diff --git a/src/libutil/config.hh b/src/libutil/config.hh
index 07322b60d7a..61a0d8d0e21 100644
--- a/src/libutil/config.hh
+++ b/src/libutil/config.hh
@@ -418,7 +418,7 @@ struct ExperimentalFeatureSettings : Config {
 
           {{#include experimental-features-shortlist.md}}
 
-          Experimental features are [further documented in the manual](@docroot@/contributing/experimental-features.md).
+          Experimental features are [further documented in the manual](@docroot@/development/experimental-features.md).
         )"};
 
     /**
diff --git a/src/nix/nix.md b/src/nix/nix.md
index 4464bef370c..f958ce09acc 100644
--- a/src/nix/nix.md
+++ b/src/nix/nix.md
@@ -50,7 +50,7 @@ manual](https://nixos.org/manual/nix/stable/).
 
 > **Warning** \
 > Installables are part of the unstable
-> [`nix-command` experimental feature](@docroot@/contributing/experimental-features.md#xp-feature-nix-command),
+> [`nix-command` experimental feature](@docroot@/development/experimental-features.md#xp-feature-nix-command),
 > and subject to change without notice.
 
 Many `nix` subcommands operate on one or more *installables*.
@@ -70,9 +70,9 @@ That is, Nix will operate on the default flake output attribute of the flake in
 
 > **Warning** \
 > Flake output attribute installables depend on both the
-> [`flakes`](@docroot@/contributing/experimental-features.md#xp-feature-flakes)
+> [`flakes`](@docroot@/development/experimental-features.md#xp-feature-flakes)
 > and
-> [`nix-command`](@docroot@/contributing/experimental-features.md#xp-feature-nix-command)
+> [`nix-command`](@docroot@/development/experimental-features.md#xp-feature-nix-command)
 > experimental features, and subject to change without notice.
 
 Example: `nixpkgs#hello`

From 66ec1560e5741e3a392423b1dab60e59cbc42027 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Thu, 13 Jun 2024 11:40:38 +0200
Subject: [PATCH 4/4] fix links

---
 doc/manual/generate-manpage.nix             | 2 +-
 doc/manual/redirects.js                     | 2 +-
 doc/manual/src/development/building.md      | 2 +-
 doc/manual/src/development/documentation.md | 2 +-
 doc/manual/src/development/index.md         | 2 +-
 src/libstore/globals.hh                     | 2 +-
 6 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/doc/manual/generate-manpage.nix b/doc/manual/generate-manpage.nix
index ba5667a4305..6ccc9049c61 100644
--- a/doc/manual/generate-manpage.nix
+++ b/doc/manual/generate-manpage.nix
@@ -38,7 +38,7 @@ let
       result = ''
         > **Warning** \
         > This program is
-        > [**experimental**](@docroot@/contributing/experimental-features.md#xp-feature-nix-command)
+        > [**experimental**](@docroot@/development/experimental-features.md#xp-feature-nix-command)
         > and its interface is subject to change.
 
         # Name
diff --git a/doc/manual/redirects.js b/doc/manual/redirects.js
index bd99fe57b8d..f31ab385143 100644
--- a/doc/manual/redirects.js
+++ b/doc/manual/redirects.js
@@ -143,7 +143,7 @@ const redirects = {
     "opt-timeout": "command-ref/opt-common.html#opt-timeout",
     "sec-common-options": "command-ref/opt-common.html",
     "ch-utilities": "command-ref/utilities.html",
-    "chap-hacking": "contributing/hacking.html",
+    "chap-hacking": "development/building.html",
     "adv-attr-allowSubstitutes": "language/advanced-attributes.html#adv-attr-allowSubstitutes",
     "adv-attr-allowedReferences": "language/advanced-attributes.html#adv-attr-allowedReferences",
     "adv-attr-allowedRequisites": "language/advanced-attributes.html#adv-attr-allowedRequisites",
diff --git a/doc/manual/src/development/building.md b/doc/manual/src/development/building.md
index 06482afe79a..308ba352117 100644
--- a/doc/manual/src/development/building.md
+++ b/doc/manual/src/development/building.md
@@ -11,7 +11,7 @@ $ cd nix
 > **Note**
 >
 > The following instructions assume you already have some version of Nix installed locally, so that you can use it to set up the development environment.
-> If you don't have it installed, follow the [installation instructions](../installation/installation.md).
+> If you don't have it installed, follow the [installation instructions](../installation/index.md).
 
 
 To build all dependencies and start a shell in which all environment variables are set up so that those dependencies can be found:
diff --git a/doc/manual/src/development/documentation.md b/doc/manual/src/development/documentation.md
index 6e7c0a9679a..5c9abff9b83 100644
--- a/doc/manual/src/development/documentation.md
+++ b/doc/manual/src/development/documentation.md
@@ -24,7 +24,7 @@ nix build .#^doc
 
 and open `./result-doc/share/doc/nix/manual/index.html`.
 
-To build the manual incrementally, [enter the development shell](./hacking.md) and run:
+To build the manual incrementally, [enter the development shell](./building.md) and run:
 
 ```console
 make manual-html-open -j $NIX_BUILD_CORES
diff --git a/doc/manual/src/development/index.md b/doc/manual/src/development/index.md
index 4d55c17a46f..6403c3e66a4 100644
--- a/doc/manual/src/development/index.md
+++ b/doc/manual/src/development/index.md
@@ -5,4 +5,4 @@ Check the [contributing guide](https://github.com/NixOS/nix/blob/master/CONTRIBU
 
 This chapter is a collection of guides for making changes to the code and documentation.
 
-If you're not sure where to start, try to [compile Nix from source](./hacking.md) and consider [making improvements to documentation](./documentation.md).
+If you're not sure where to start, try to [compile Nix from source](./building.md) and consider [making improvements to documentation](./documentation.md).
diff --git a/src/libstore/globals.hh b/src/libstore/globals.hh
index 39703270068..5b5fcfb410d 100644
--- a/src/libstore/globals.hh
+++ b/src/libstore/globals.hh
@@ -303,7 +303,7 @@ public:
              For backward compatibility, `ssh://` may be omitted.
              The hostname may be an alias defined in `~/.ssh/config`.
 
-          2. A comma-separated list of [Nix system types](@docroot@/development/hacking.md#system-type).
+          2. A comma-separated list of [Nix system types](@docroot@/development/building.md#system-type).
              If omitted, this defaults to the local platform type.
 
              > **Example**