NixOS · SaltyKitkat · May 21, 2023 · Jun 17, 2023 · Jun 17, 2023 · Jun 17, 2023
diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
@@ -58,13 +58,9 @@
 /maintainers/scripts/db-to-md.sh @jtojnar @ryantm
 /maintainers/scripts/doc @jtojnar @ryantm
 
-/doc/* @fricklerhandwerk
 /doc/build-aux/pandoc-filters @jtojnar
-/doc/builders/trivial-builders.chapter.md @fricklerhandwerk
 /doc/contributing/ @fricklerhandwerk
 /doc/contributing/contributing-to-documentation.chapter.md @jtojnar @fricklerhandwerk
-/doc/stdenv @fricklerhandwerk
-/doc/using @fricklerhandwerk
 
 # NixOS Internals
 /nixos/default.nix                                    @infinisil
@@ -302,9 +298,9 @@ pkgs/development/python-modules/buildcatrust/ @ajs124 @lukegb @mweinelt
 /doc/languages-frameworks/javascript.section.md @winterqt
 
 # OCaml
-/pkgs/build-support/ocaml           @romildo @ulrikstrid
-/pkgs/development/compilers/ocaml   @romildo @ulrikstrid
-/pkgs/development/ocaml-modules     @romildo @ulrikstrid
+/pkgs/build-support/ocaml           @ulrikstrid
+/pkgs/development/compilers/ocaml   @ulrikstrid
+/pkgs/development/ocaml-modules     @ulrikstrid
 
 # ZFS
 pkgs/os-specific/linux/zfs                @raitobezarius

diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
@@ -22,7 +22,7 @@ For new packages please briefly describe the package or provide a link to its ho
   - made sure NixOS tests are [linked](https://nixos.org/manual/nixpkgs/unstable/#ssec-nixos-tests-linking) to the relevant packages
 - [ ] Tested compilation of all packages that depend on this change using `nix-shell -p nixpkgs-review --run "nixpkgs-review rev HEAD"`. Note: all changes have to be committed, also see [nixpkgs-review usage](https://github.com/Mic92/nixpkgs-review#usage)
 - [ ] Tested basic functionality of all binary files (usually in `./result/bin/`)
-- [23.11 Release Notes (or backporting 23.05 Release notes)](https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md#generating-2305-release-notes)
+- [23.11 Release Notes](https://github.com/NixOS/nixpkgs/blob/master/nixos/doc/manual/release-notes/rl-2311.section.md) (or backporting [23.05 Release notes](https://github.com/NixOS/nixpkgs/blob/master/nixos/doc/manual/release-notes/rl-2305.section.md))
   - [ ] (Package updates) Added a release notes entry if the change is major or breaking
   - [ ] (Module updates) Added a release notes entry if the change is significant
   - [ ] (Module addition) Added a release notes entry if adding a new NixOS module

diff --git a/.github/workflows/backport.yml b/.github/workflows/backport.yml
@@ -24,7 +24,7 @@ jobs:
         with:
           ref: ${{ github.event.pull_request.head.sha }}
       - name: Create backport PRs
-        uses: korthout/backport-action@v1.2.0
+        uses: korthout/backport-action@v1.3.1
         with:
           # Config README: https://github.com/korthout/backport-action#backport-action
           copy_labels_pattern: 'severity:\ssecurity'

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -66,9 +66,12 @@ Useful git commands that can help a lot with this are `git commit --patch --amen
 From time to time, changes between branches must be rebased, for example, if the
 number of new rebuilds they would cause is too large for the target branch. When
 rebasing, care must be taken to include only the intended changes, otherwise
-many CODEOWNERS will be inadvertently requested for review.  To achieve this,
+many CODEOWNERS will be inadvertently requested for review. To achieve this,
 rebasing should not be performed directly on the target branch, but on the merge
-base between the current and target branch.
+base between the current and target branch. As an additional precautionary measure,
+you should temporarily mark the PR as draft for the duration of the operation.
+This reduces the probability of mass-pinging people. (OfBorg might still
+request a couple of persons for reviews though.)
 
 In the following example, we assume that the current branch, called `feature`,
 is based on `master`, and we rebase it onto the merge base between
@@ -102,6 +105,36 @@ git status
 git push origin feature --force-with-lease
 ```
 
+### Something went wrong and a lot of people were pinged
+
+It happens. Remember to be kind, especially to new contributors.
+There is no way back, so the pull request should be closed and locked
+(if possible). The changes should be re-submitted in a new PR, in which the people
+originally involved in the conversation need to manually be pinged again.
+No further discussion should happen on the original PR, as a lot of people
+are now subscribed to it.
+
+The following message (or a version thereof) might be left when closing to
+describe the situation, since closing and locking without any explanation
+is kind of rude:
+
+```markdown
+It looks like you accidentally mass-pinged a bunch of people, which are now subscribed
+and getting notifications for everything in this pull request. Unfortunately, they
+cannot be automatically unsubscribed from the issue (removing review request does not
+unsubscribe), therefore development cannot continue in this pull request anymore.
+
+Please open a new pull request with your changes, link back to this one and ping the
+people actually involved in here over there.
+
+In order to avoid this in the future, there are instructions for how to properly
+rebase between branches in our [contribution guidelines](https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md#rebasing-between-branches-ie-from-master-to-staging).
+Setting your pull request to draft prior to rebasing is strongly recommended.
+In draft status, you can preview the list of people that are about to be requested
+for review, which allows you to sidestep this issue.
+This is not a bulletproof method though, as OfBorg still does review requests even on draft PRs.
+```
+
 ## Backporting changes
 
 Follow these steps to backport a change into a release branch in compliance with the [commit policy](https://nixos.org/nixpkgs/manual/#submitting-changes-stable-release-branches).
@@ -128,19 +161,6 @@ Anything that does not cause user or downstream dependency regressions can be ba
 - Services which require a client to be up-to-date regardless. (E.g. `spotify`, `steam`, or `discord`)
 - Security critical applications (E.g. `firefox`)
 
-## Generating 23.11 Release Notes
-<!--
-note: title unchanged even though we don't need regeneration because extant
-PRs will link here. definitely change the title for 23.11 though.
--->
-
-Documentation in nixpkgs is transitioning to a markdown-centric workflow. In the past release notes required a translation step to convert from markdown to a compatible docbook document, but this is no longer necessary.
-
-Steps for updating 23.11 Release notes:
-
-1. Edit `nixos/doc/manual/release-notes/rl-2311.section.md` with the desired changes
-2. Commit changes to `rl-2311.section.md`.
-
 ## Reviewing contributions
 
 See the nixpkgs manual for more details on how to [Review contributions](https://nixos.org/nixpkgs/manual/#chap-reviewing-contributions).
diff --git a/doc/Makefile b/doc/Makefile
@@ -66,18 +66,13 @@ out/html/index.html: doc-support/result manual-full.xml style.css highlightjs
 	cp doc-support/result/xsl/docbook/images/callouts/*.svg out/html/images/callouts/
 	chmod u+w -R out/html/
 
-out/epub/manual.epub: manual-full.xml
+out/epub/manual.epub: epub.xml
 	mkdir -p out/epub/scratch
 	xsltproc --nonet \
 		--output out/epub/scratch/ \
 		doc-support/result/epub.xsl \
-		./manual-full.xml
+		./epub.xml
 
-	cp -r $(pandoc_media_dir) out/epub/scratch/OEBPS
-	cp ./overrides.css out/epub/scratch/OEBPS
-	cp ./style.css out/epub/scratch/OEBPS
-	mkdir -p out/epub/scratch/OEBPS/images/callouts/
-	cp doc-support/result/xsl/docbook/images/callouts/*.svg out/epub/scratch/OEBPS/images/callouts/
 	echo "application/epub+zip" > mimetype
 	zip -0Xq "out/epub/manual.epub" mimetype
 	rm mimetype

diff --git a/doc/builders/fetchers.chapter.md b/doc/builders/fetchers.chapter.md
@@ -132,19 +132,24 @@ A number of fetcher functions wrap part of `fetchurl` and `fetchzip`. They are m
 
 `fetchFromGitHub` expects four arguments. `owner` is a string corresponding to the GitHub user or organization that controls this repository. `repo` corresponds to the name of the software repository. These are located at the top of every GitHub HTML page as `owner`/`repo`. `rev` corresponds to the Git commit hash or tag (e.g `v1.0`) that will be downloaded from Git. Finally, `hash` corresponds to the hash of the extracted directory. Again, other hash algorithms are also available, but `hash` is currently preferred.
 
+To use a different GitHub instance, use `githubBase` (defaults to `"github.com"`).
+
 `fetchFromGitHub` uses `fetchzip` to download the source archive generated by GitHub for the specified revision. If `leaveDotGit`, `deepClone` or `fetchSubmodules` are set to `true`, `fetchFromGitHub` will use `fetchgit` instead. Refer to its section for documentation of these options.
 
 ## `fetchFromGitLab` {#fetchfromgitlab}
 
-This is used with GitLab repositories. The arguments expected are very similar to `fetchFromGitHub` above.
+This is used with GitLab repositories. It behaves similarly to `fetchFromGitHub`, and expects `owner`, `repo`, `rev`, and `hash`.
+
+To use a specific GitLab instance, use `domain` (defaults to `"gitlab.com"`).
+
 
 ## `fetchFromGitiles` {#fetchfromgitiles}
 
 This is used with Gitiles repositories. The arguments expected are similar to `fetchgit`.
 
 ## `fetchFromBitbucket` {#fetchfrombitbucket}
 
-This is used with BitBucket repositories. The arguments expected are very similar to fetchFromGitHub above.
+This is used with BitBucket repositories. The arguments expected are very similar to `fetchFromGitHub` above.
 
 ## `fetchFromSavannah` {#fetchfromsavannah}
 

diff --git a/doc/builders/special/darwin-builder.section.md b/doc/builders/special/darwin-builder.section.md
@@ -62,7 +62,7 @@ builders-use-substitutes = true
 $ sudo launchctl kickstart -k system/org.nixos.nix-daemon
 ```
 
-## Example flake usage
+## Example flake usage {#sec-darwin-builder-example-flake}
 
 ```
 {
@@ -120,7 +120,7 @@ $ sudo launchctl kickstart -k system/org.nixos.nix-daemon
 }
 ```
 
-## Reconfiguring the builder
+## Reconfiguring the builder {#sec-darwin-builder-reconfiguring}
 
 Initially you should not change the builder configuration else you will not be
 able to use the binary cache. However, after you have the builder running locally

diff --git a/doc/builders/special/makesetuphook.section.md b/doc/builders/special/makesetuphook.section.md
@@ -12,7 +12,7 @@ pkgs.makeSetupHook {
 } ./script.sh
 ```
 
-#### setup hook that depends on the hello package and runs hello and @shell@ is substituted with path to bash {#sec-pkgs.makeSetupHook-usage-example}
+### setup hook that depends on the hello package and runs hello and @shell@ is substituted with path to bash {#sec-pkgs.makeSetupHook-usage-example}
 
 ```nix
 pkgs.makeSetupHook {

diff --git a/doc/builders/special/vm-tools.section.md b/doc/builders/special/vm-tools.section.md
@@ -6,7 +6,7 @@ A set of VM related utilities, that help in building some packages in more advan
 
 A bash script fragment that produces a disk image at `destination`.
 
-### Attributes
+### Attributes {#vm-tools-createEmptyImage-attributes}
 
 * `size`. The disk size, in MiB.
 * `fullName`. Name that will be written to `${destination}/nix-support/full-name`.
@@ -20,14 +20,14 @@ Thus, any pure Nix derivation should run unmodified.
 
 If the build fails and Nix is run with the `-K/--keep-failed` option, a script `run-vm` will be left behind in the temporary build directory that allows you to boot into the VM and debug it interactively.
 
-### Attributes
+### Attributes {#vm-tools-runInLinuxVM-attributes}
 
 * `preVM` (optional). Shell command to be evaluated *before* the VM is started (i.e., on the host).
 * `memSize` (optional, default `512`). The memory size of the VM in MiB.
 * `diskImage` (optional). A file system image to be attached to `/dev/sda`.
   Note that currently we expect the image to contain a filesystem, not a full disk image with a partition table etc.
 
-### Examples
+### Examples {#vm-tools-runInLinuxVM-examples}
 
 Build the derivation hello inside a VM:
 ```nix
@@ -56,13 +56,13 @@ runInLinuxVM (hello.overrideAttrs (_: {
 
 Takes a file, such as an ISO, and extracts its contents into the store.
 
-### Attributes
+### Attributes {#vm-tools-extractFs-attributes}
 
 * `file`. Path to the file to be extracted.
   Note that currently we expect the image to contain a filesystem, not a full disk image with a partition table etc.
 * `fs` (optional). Filesystem of the contents of the file.
 
-### Examples
+### Examples {#vm-tools-extractFs-examples}
 
 Extract the contents of an ISO file:
 ```nix
@@ -82,7 +82,7 @@ Like [](#vm-tools-runInLinuxVM), but instead of using `stdenv` from the Nix stor
 
 Generate a script that can be used to run an interactive session in the given image.
 
-### Examples
+### Examples {#vm-tools-makeImageTestScript-examples}
 
 Create a script for running a Fedora 27 VM:
 ```nix
@@ -100,7 +100,7 @@ makeImageTestScript diskImages.ubuntu2004x86_64
 
 A set of functions that build a predefined set of minimal Linux distributions images.
 
-### Images
+### Images {#vm-tools-diskImageFuns-images}
 
 * Fedora
   * `fedora26x86_64`
@@ -126,12 +126,12 @@ A set of functions that build a predefined set of minimal Linux distributions im
   * `debian11i386`
   * `debian11x86_64`
 
-### Attributes
+### Attributes {#vm-tools-diskImageFuns-attributes}
 
 * `size` (optional, defaults to `4096`). The size of the image, in MiB.
 * `extraPackages` (optional). A list names of additional packages from the distribution that should be included in the image.
 
-### Examples
+### Examples {#vm-tools-diskImageFuns-examples}
 
 8GiB image containing Firefox in addition to the default packages:
 ```nix

diff --git a/doc/builders/testers.chapter.md b/doc/builders/testers.chapter.md
@@ -1,5 +1,5 @@
 # Testers {#chap-testers}
-This chapter describes several testing builders which are available in the <literal>testers</literal> namespace.
+This chapter describes several testing builders which are available in the `testers` namespace.
 
 ## `hasPkgConfigModule` {#tester-hasPkgConfigModule}
 

diff --git a/doc/contributing/coding-conventions.chapter.md b/doc/contributing/coding-conventions.chapter.md
@@ -220,7 +220,9 @@ There are a few naming guidelines:
 
 - The `version` attribute _must_ start with a digit e.g`"0.3.1rc2".
 
-- If a package is not a release but a commit from a repository, then the `version` attribute _must_ be the date of that (fetched) commit. The date _must_ be in `"unstable-YYYY-MM-DD"` format.
+- If a package is a commit from a repository without a version assigned, then the `version` attribute _should_ be the latest upstream version preceding that commit, followed by `-unstable-` and the date of the (fetched) commit. The date _must_ be in `"YYYY-MM-DD"` format.
+
+Example: Given a project had its latest releases `2.2` in November 2021, and `3.0` in January 2022, a commit authored on March 15, 2022 for an upcoming bugfix release `2.2.1` would have `version = "2.2-unstable-2022-03-15"`.
 
 - Dashes in the package `pname` _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.
 

diff --git a/doc/contributing/reviewing-contributions.chapter.md b/doc/contributing/reviewing-contributions.chapter.md
@@ -12,7 +12,7 @@ When reviewing a pull request, please always be nice and polite. Controversial c
 
 GitHub provides reactions as a simple and quick way to provide feedback to pull requests or any comments. The thumb-down reaction should be used with care and if possible accompanied with some explanation so the submitter has directions to improve their contribution.
 
-pull request reviews should include a list of what has been reviewed in a comment, so other reviewers and mergers can know the state of the review.
+Pull request reviews should include a list of what has been reviewed in a comment, so other reviewers and mergers can know the state of the review.
 
 All the review template samples provided in this section are generic and meant as examples. Their usage is optional and the reviewer is free to adapt them to their liking.
 
@@ -201,7 +201,7 @@ checks should be performed:
     them to either recommit using that key or to remove their key
     information.
 
-    Given a maintainter entry like this:
+    Given a maintainer entry like this:
 
     ``` nix
     {

diff --git a/doc/default.nix b/doc/default.nix
@@ -20,7 +20,33 @@ in pkgs.stdenv.mkDerivation {
     ln -s ${doc-support} ./doc-support/result
   '';
 
+  epub = ''
+    <book xmlns="http://docbook.org/ns/docbook"
+          xmlns:xlink="http://www.w3.org/1999/xlink"
+          version="5.0"
+          xml:id="nixpkgs-manual">
+      <info>
+        <title>Nixpkgs Manual</title>
+        <subtitle>Version ${pkgs.lib.version}</subtitle>
+      </info>
+      <chapter>
+        <title>Temporarily unavailable</title>
+        <para>
+          The Nixpkgs manual is currently not available in EPUB format,
+          please use the <link xlink:href="https://nixos.org/nixpkgs/manual">HTML manual</link>
+          instead.
+        </para>
+        <para>
+          If you've used the EPUB manual in the past and it has been useful to you, please
+          <link xlink:href="https://github.com/NixOS/nixpkgs/issues/237234">let us know</link>.
+        </para>
+      </chapter>
+    </book>
+  '';
+  passAsFile = [ "epub" ];
+
   preBuild = ''
+    cp $epubPath epub.xml
     make -j$NIX_BUILD_CORES render-md
   '';
 

diff --git a/doc/functions/generators.section.md b/doc/functions/generators.section.md
@@ -16,7 +16,7 @@ let
              if v == true then ''"yes"''
         else if v == false then ''"no"''
         else if isString v then ''"${v}"''
-        # and delegats all other values to the default generator
+        # and delegates all other values to the default generator
         else generators.mkValueStringDefault {} v;
     } ":";
   };

diff --git a/doc/hooks/autoconf.section.md b/doc/hooks/autoconf.section.md
@@ -1,4 +1,3 @@
-
-### Autoconf {#setup-hook-autoconf}
+# Autoconf {#setup-hook-autoconf}
 
 The `autoreconfHook` derivation adds `autoreconfPhase`, which runs autoreconf, libtoolize and automake, essentially preparing the configure script in autotools-based builds. Most autotools-based packages come with the configure script pre-generated, but this hook is necessary for a few packages and when you need to patch the package’s configure scripts.
diff --git a/doc/hooks/automake.section.md b/doc/hooks/automake.section.md
@@ -1,4 +1,3 @@
-
-### Automake {#setup-hook-automake}
+# Automake {#setup-hook-automake}
 
 Adds the `share/aclocal` subdirectory of each build input to the `ACLOCAL_PATH` environment variable.
diff --git a/doc/hooks/autopatchelf.section.md b/doc/hooks/autopatchelf.section.md
@@ -1,5 +1,4 @@
-
-### autoPatchelfHook {#setup-hook-autopatchelfhook}
+# autoPatchelfHook {#setup-hook-autopatchelfhook}
 
 This is a special setup hook which helps in packaging proprietary software in that it automatically tries to find missing shared library dependencies of ELF files based on the given `buildInputs` and `nativeBuildInputs`.
 

diff --git a/doc/hooks/breakpoint.section.md b/doc/hooks/breakpoint.section.md
@@ -1,5 +1,4 @@
-
-### breakpointHook {#breakpointhook}
+# breakpointHook {#breakpointhook}
 
 This hook will make a build pause instead of stopping when a failure happens. It prevents nix from cleaning up the build environment immediately and allows the user to attach to a build environment using the `cntr` command. Upon build error it will print instructions on how to use `cntr`, which can be used to enter the environment for debugging. Installing cntr and running the command will provide shell access to the build sandbox of failed build. At `/var/lib/cntr` the sandboxed filesystem is mounted. All commands and files of the system are still accessible within the shell. To execute commands from the sandbox use the cntr exec subcommand. `cntr` is only supported on Linux-based platforms. To use it first add `cntr` to your `environment.systemPackages` on NixOS or alternatively to the root user on non-NixOS systems. Then in the package that is supposed to be inspected, add `breakpointHook` to `nativeBuildInputs`.
 

diff --git a/doc/hooks/cmake.section.md b/doc/hooks/cmake.section.md
@@ -1,4 +1,3 @@
-
-### cmake {#cmake}
+# cmake {#cmake}
 
 Overrides the default configure phase to run the CMake command. By default, we use the Make generator of CMake. In addition, dependencies are added automatically to `CMAKE_PREFIX_PATH` so that packages are correctly detected by CMake. Some additional flags are passed in to give similar behavior to configure-based packages. You can disable this hook’s behavior by setting `configurePhase` to a custom value, or by setting `dontUseCmakeConfigure`. `cmakeFlags` controls flags passed only to CMake. By default, parallel building is enabled as CMake supports parallel building almost everywhere. When Ninja is also in use, CMake will detect that and use the ninja generator.
diff --git a/doc/hooks/gdk-pixbuf.section.md b/doc/hooks/gdk-pixbuf.section.md
@@ -1,4 +1,3 @@
-
-### gdk-pixbuf {#setup-hook-gdk-pixbuf}
+# gdk-pixbuf {#setup-hook-gdk-pixbuf}
 
 Exports `GDK_PIXBUF_MODULE_FILE` environment variable to the builder. Add librsvg package to `buildInputs` to get svg support. See also the [setup hook description in GNOME platform docs](#ssec-gnome-hooks-gdk-pixbuf).
diff --git a/doc/hooks/ghc.section.md b/doc/hooks/ghc.section.md
@@ -1,4 +1,3 @@
-
-### GHC {#ghc}
+# GHC {#ghc}
 
 Creates a temporary package database and registers every Haskell build input in it (TODO: how?).