8 files changed, 57 insertions, 14 deletions
diff --git a/doc/builders/fetchers.chapter.md b/doc/builders/fetchers.chapter.md
index 5b28b2dcb398a..28388ba685d8f 100644
--- a/doc/builders/fetchers.chapter.md
+++ b/doc/builders/fetchers.chapter.md
@@ -40,6 +40,24 @@ Used with Git. Expects `url` to a Git repo, `rev`, and `sha256`. `rev` in this c
 
 Additionally the following optional arguments can be given: `fetchSubmodules = true` makes `fetchgit` also fetch the submodules of a repository. If `deepClone` is set to true, the entire repository is cloned as opposing to just creating a shallow clone. `deepClone = true` also implies `leaveDotGit = true` which means that the `.git` directory of the clone won't be removed after checkout.
 
+If only parts of the repository are needed, `sparseCheckout` can be used. This will prevent git from fetching unnecessary blobs from server, see [git sparse-checkout](https://git-scm.com/docs/git-sparse-checkout) and [git clone --filter](https://git-scm.com/docs/git-clone#Documentation/git-clone.txt---filterltfilter-specgt) for more infomation:
+
+```nix
+{ stdenv, fetchgit }:
+
+stdenv.mkDerivation {
+  name = "hello";
+  src = fetchgit {
+    url = "https://...";
+    sparseCheckout = ''
+      path/to/be/included
+      another/path
+    '';
+    sha256 = "0000000000000000000000000000000000000000000000000000";
+  };
+}
+```
+
 ## `fetchfossil` {#fetchfossil}
 
 Used with Fossil. Expects `url` to a Fossil archive, `rev`, and `sha256`.
diff --git a/doc/contributing/coding-conventions.chapter.md b/doc/contributing/coding-conventions.chapter.md
index 79d90c23a40f9..cfe8582e514a4 100644
--- a/doc/contributing/coding-conventions.chapter.md
+++ b/doc/contributing/coding-conventions.chapter.md
@@ -224,7 +224,7 @@ There are a few naming guidelines:
 
 - Dashes in the package name _should_ be preserved in new variable names, rather than converted to underscores or camel cased — e.g., `http-parser` instead of `http_parser` or `httpParser`. The hyphenated style is preferred in all three package names.
 
-- If there are multiple versions of a package, this _should_ be reflected in the variable names in `all-packages.nix`, e.g. `json-c-0-9` and `json-c-0-11`. If there is an obvious “default” version, make an attribute like `json-c = json-c-0-9;`. See also [](#sec-versioning)
+- If there are multiple versions of a package, this _should_ be reflected in the variable names in `all-packages.nix`, e.g. `json-c_0_9` and `json-c_0_11`. If there is an obvious “default” version, make an attribute like `json-c = json-c_0_9;`. See also [](#sec-versioning)
 
 ## File naming and organisation {#sec-organisation}
 
diff --git a/doc/contributing/reviewing-contributions.chapter.md b/doc/contributing/reviewing-contributions.chapter.md
index 3f3ba60947ccd..0a90781d0c59e 100644
--- a/doc/contributing/reviewing-contributions.chapter.md
+++ b/doc/contributing/reviewing-contributions.chapter.md
@@ -103,7 +103,8 @@ Sample template for a new package review is provided below.
 - [ ] `meta.maintainers` is set
 - [ ] build time only dependencies are declared in `nativeBuildInputs`
 - [ ] source is fetched using the appropriate function
-- [ ] phases are respected
+- [ ] the list of `phases` is not overridden
+- [ ] when a phase (like `installPhase`) is overridden it starts with `runHook preInstall` and ends with `runHook postInstall`.
 - [ ] patches that are remotely available are fetched with `fetchpatch`
 
 ##### Possible improvements
diff --git a/doc/contributing/submitting-changes.chapter.md b/doc/contributing/submitting-changes.chapter.md
index 09ffba3dc6fc5..d5b5f5a601752 100644
--- a/doc/contributing/submitting-changes.chapter.md
+++ b/doc/contributing/submitting-changes.chapter.md
@@ -227,7 +227,7 @@ digraph {
 }
 ```
 
-[This GitHub Action](https://github.com/NixOS/nixpkgs/blob/master/.github/workflows/merge-staging.yml) brings changes from `master` to `staging-next` and from `staging-next` to `staging` every 6 hours.
+[This GitHub Action](https://github.com/NixOS/nixpkgs/blob/master/.github/workflows/periodic-merge-6h.yml) brings changes from `master` to `staging-next` and from `staging-next` to `staging` every 6 hours.
 
 
 ### Master branch {#submitting-changes-master-branch}
diff --git a/doc/languages-frameworks/dotnet.section.md b/doc/languages-frameworks/dotnet.section.md
index 88e1a0b295968..f7af28a167752 100644
--- a/doc/languages-frameworks/dotnet.section.md
+++ b/doc/languages-frameworks/dotnet.section.md
@@ -84,7 +84,7 @@ To package Dotnet applications, you can use `buildDotnetModule`. This has simila
      <ProjectReference Include="../foo/bar.fsproj" />
      <PackageReference Include="bar" Version="*" Condition=" '$(ContinuousIntegrationBuild)'=='true' "/>
   ```
-* `executables` is used to specify which executables get wrapped to `$out/bin`, relative to `$out/lib/$pname`. If this is unset, all executables generated will get installed. If you do not want to install any, set this to `[]`.
+* `executables` is used to specify which executables get wrapped to `$out/bin`, relative to `$out/lib/$pname`. If this is unset, all executables generated will get installed. If you do not want to install any, set this to `[]`. This gets done in the `preFixup` phase.
 * `runtimeDeps` is used to wrap libraries into `LD_LIBRARY_PATH`. This is how dotnet usually handles runtime dependencies.
 * `buildType` is used to change the type of build. Possible values are `Release`, `Debug`, etc. By default, this is set to `Release`.
 * `dotnet-sdk` is useful in cases where you need to change what dotnet SDK is being used.
diff --git a/doc/languages-frameworks/ocaml.section.md b/doc/languages-frameworks/ocaml.section.md
index d266a032268c8..47035551d4181 100644
--- a/doc/languages-frameworks/ocaml.section.md
+++ b/doc/languages-frameworks/ocaml.section.md
@@ -32,9 +32,9 @@ Given that most of the OCaml ecosystem is now built with dune, nixpkgs includes
 
 Here is a simple package example.
 
-- It defines an (optional) attribute `minimalOCamlVersion` that will be used to
-  throw a descriptive evaluation error if building with an older OCaml is
-  attempted.
+- It defines an (optional) attribute `minimalOCamlVersion` (see note below)
+  that will be used to throw a descriptive evaluation error if building with
+  an older OCaml is attempted.
 
 - It uses the `fetchFromGitHub` fetcher to get its source.
 
@@ -117,3 +117,11 @@ buildDunePackage rec {
   };
 }
 ```
+
+Note about `minimalOCamlVersion`.  A deprecated version of this argument was
+spelled `minimumOCamlVersion`; setting the old attribute wrongly modifies the
+derivation hash and is therefore inappropriate. As a technical dept, currently
+packaged libraries may still use the old spelling: maintainers are invited to
+fix this when updating packages. Massive renaming is strongly discouraged as it
+would be challenging to review, difficult to test, and will cause unnecessary
+rebuild.
diff --git a/doc/stdenv/meta.chapter.md b/doc/stdenv/meta.chapter.md
index ac518cee524cf..d3e1dd5b27d82 100644
--- a/doc/stdenv/meta.chapter.md
+++ b/doc/stdenv/meta.chapter.md
@@ -192,10 +192,6 @@ meta.hydraPlatforms = [];
 
 If set to `true`, the package is marked as "broken", meaning that it won’t show up in `nix-env -qa`, and cannot be built or installed. Such packages should be removed from Nixpkgs eventually unless they are fixed.
 
-### `updateWalker` {#var-meta-updateWalker}
-
-If set to `true`, the package is tested to be updated correctly by the `update-walker.sh` script without additional settings. Such packages have `meta.version` set and their homepage (or the page specified by `meta.downloadPage`) contains a direct link to the package tarball.
-
 ## Licenses {#sec-meta-license}
 
 The `meta.license` attribute should preferably contain a value from `lib.licenses` defined in [`nixpkgs/lib/licenses.nix`](https://github.com/NixOS/nixpkgs/blob/master/lib/licenses.nix), or in-place license description of the same format if the license is unlikely to be useful in another expression.
diff --git a/doc/stdenv/stdenv.chapter.md b/doc/stdenv/stdenv.chapter.md
index 6d72bd0deb4f8..1d4ca99e3cbe5 100644
--- a/doc/stdenv/stdenv.chapter.md
+++ b/doc/stdenv/stdenv.chapter.md
@@ -319,10 +319,16 @@ For information about how to run the updates, execute `nix-shell maintainers/scr
 
 ## Phases {#sec-stdenv-phases}
 
-The generic builder has a number of *phases*. Package builds are split into phases to make it easier to override specific parts of the build (e.g., unpacking the sources or installing the binaries). Furthermore, it allows a nicer presentation of build logs in the Nix build farm.
+`stdenv.mkDerivation` sets the Nix [derivation](https://nixos.org/manual/nix/stable/expressions/derivations.html#derivations)'s builder to a script that loads the stdenv `setup.sh` bash library and calls `genericBuild`. Most packaging functions rely on this default builder.
+
+This generic command invokes a number of *phases*. Package builds are split into phases to make it easier to override specific parts of the build (e.g., unpacking the sources or installing the binaries).
 
 Each phase can be overridden in its entirety either by setting the environment variable `namePhase` to a string containing some shell commands to be executed, or by redefining the shell function `namePhase`. The former is convenient to override a phase from the derivation, while the latter is convenient from a build script. However, typically one only wants to *add* some commands to a phase, e.g. by defining `postInstall` or `preFixup`, as skipping some of the default actions may have unexpected consequences. The default script for each phase is defined in the file `pkgs/stdenv/generic/setup.sh`.
 
+When overriding a phase, for example `installPhase`, it is important to start with `runHook preInstall` and end it with `runHook postInstall`, otherwise `preInstall` and `postInstall` will not be run. Even if you don't use them directly, it is good practice to do so anyways for downstream users who would want to add a `postInstall` by overriding your derivation.
+
+While inside an interactive `nix-shell`, if you wanted to run all phases in the order they would be run in an actual build, you can invoke `genericBuild` yourself.
+
 ### Controlling phases {#ssec-controlling-phases}
 
 There are a number of variables that control what phases are executed and in what order:
@@ -333,7 +339,8 @@ There are a number of variables that control what phases are executed and in wha
 
 Specifies the phases. You can change the order in which phases are executed, or add new phases, by setting this variable. If it’s not set, the default value is used, which is `$prePhases unpackPhase patchPhase $preConfigurePhases configurePhase $preBuildPhases buildPhase checkPhase $preInstallPhases installPhase fixupPhase installCheckPhase $preDistPhases distPhase $postPhases`.
 
-Usually, if you just want to add a few phases, it’s more convenient to set one of the variables below (such as `preInstallPhases`), as you then don’t specify all the normal phases.
+It is discouraged to set this variable, as it is easy to miss some important functionality hidden in some of the less obviously needed phases (like `fixupPhase` which patches the shebang of scripts).
+Usually, if you just want to add a few phases, it’s more convenient to set one of the variables below (such as `preInstallPhases`).
 
 ##### `prePhases` {#var-stdenv-prePhases}
 
@@ -790,7 +797,7 @@ Hook executed at the start of the distribution phase.
 
 Hook executed at the end of the distribution phase.
 
-## Shell functions {#ssec-stdenv-functions}
+## Shell functions and utilities {#ssec-stdenv-functions}
 
 The standard environment provides a number of useful functions.
 
@@ -814,6 +821,19 @@ There’s many more kinds of arguments, they are documented in `nixpkgs/pkgs/bui
 
 Using the `makeBinaryWrapper` implementation is usually preferred, as it creates a tiny _compiled_ wrapper executable, that can be used as a shebang interpreter. This is needed mostly on Darwin, where shebangs cannot point to scripts, [due to a limitation with the `execve`-syscall](https://stackoverflow.com/questions/67100831/macos-shebang-with-absolute-path-not-working). Compiled wrappers generated by `makeBinaryWrapper` can be inspected with `less <path-to-wrapper>` - by scrolling past the binary data you should be able to see the shell command that generated the executable and there see the environment variables that were injected into the wrapper.
 
+### `remove-references-to -t` \<storepath\> [ `-t` \<storepath\> ... ] \<file\> ... {#fun-remove-references-to}
+
+Removes the references of the specified files to the specified store files. This is done without changing the size of the file by replacing the hash by `eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee`, and should work on compiled executables. This is meant to be used to remove the dependency of the output on inputs that are known to be unnecessary at runtime. Of course, reckless usage will break the patched programs.
+To use this, add `removeReferencesTo` to `nativeBuildInputs`.
+
+As `remove-references-to` is an actual executable and not a shell function, it can be used with `find`.
+Example removing all references to the compiler in the output:
+```nix
+postInstall = ''
+  find "$out" -type f -exec remove-references-to -t ${stdenv.cc} '{}' +
+'';
+```
+
 ### `substitute` \<infile\> \<outfile\> \<subs\> {#fun-substitute}
 
 Performs string substitution on the contents of \<infile\>, writing the result to \<outfile\>. The substitutions in \<subs\> are of the following form: