doc: Add staging workflow diagram

doc/Makefile

@@ -39,6 +39,7 @@ out/html/index.html: doc-support/result manual-full.xml style.css highlightjs
 	mkdir -p out/html/highlightjs/
 	cp -r highlightjs out/html/
 
+	cp -r media out/html/
 	cp ./overrides.css out/html/
 	cp ./style.css out/html/style.css
 
@@ -53,6 +54,7 @@ out/epub/manual.epub: manual-full.xml
 		doc-support/result/epub.xsl \
 		./manual-full.xml
 
+	cp -r media 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/
@@ -88,11 +90,15 @@ functions/library/generated: doc-support/result
 
 %.section.xml: %.section.md
 	pandoc $^ -t docbook \
+		--extract-media=media \
+		--lua-filter=$(PANDOC_LUA_FILTERS_DIR)/diagram-generator.lua \
 		-f markdown+smart \
 	| cat  > $@
 
 %.chapter.xml: %.chapter.md
 	pandoc $^ -t docbook \
 		--top-level-division=chapter \
+		--extract-media=media \
+		--lua-filter=$(PANDOC_LUA_FILTERS_DIR)/diagram-generator.lua \
 		-f markdown+smart \
 	| cat  > $@

doc/contributing/submitting-changes.chapter.md

@@ -159,6 +159,25 @@ The last checkbox is fits [CONTRIBUTING.md](https://github.com/NixOS/nixpkgs/blo
 - Hydra builds for master and staging should not be used as testing platform, it’s a build farm for changes that have been already tested.
 - When changing the bootloader installation process, extra care must be taken. Grub installations cannot be rolled back, hence changes may break people’s installations forever. For any non-trivial change to the bootloader please file a PR asking for review, especially from \@edolstra.
 
+```{.graphviz caption="Staging workflow"}
+digraph {
+    "small changes" [shape=none]
+    "mass-rebuilds and other large changes" [shape=none]
+    "critical security fixes" [shape=none]
+    "broken staging-next fixes" [shape=none]
+
+    "small changes" -> master
+    "mass-rebuilds and other large changes" -> staging
+    "critical security fixes" -> master
+    "broken staging-next fixes" -> "staging-next"
+
+    "staging-next" -> master [color="#E85EB0"] [label="stabilization ends"] [fontcolor="#E85EB0"]
+    "staging" -> "staging-next" [color="#E85EB0"] [label="stabilization starts"] [fontcolor="#E85EB0"]
+
+    master -> "staging-next" -> staging [color="#5F5EE8"] [label="every six hours/any time"] [fontcolor="#5F5EE8"]
+}
+```
+
 ### Master branch {#submitting-changes-master-branch}
 
 The `master` branch is the main development branch. It should only see non-breaking commits that do not cause mass rebuilds.

doc/default.nix

@@ -5,10 +5,22 @@ let
 in pkgs.stdenv.mkDerivation {
   name = "nixpkgs-manual";
 
-  buildInputs = with pkgs; [ pandoc libxml2 libxslt zip jing  xmlformat ];
+  nativeBuildInputs = with pkgs; [
+    pandoc
+    graphviz
+    libxml2
+    libxslt
+    zip
+    jing
+    xmlformat
+  ];
 
   src = ./.;
 
+  makeFlags = [
+    "PANDOC_LUA_FILTERS_DIR=${pkgs.pandoc-lua-filters}/share/pandoc/filters"
+  ];
+
   postPatch = ''
     ln -s ${doc-support} ./doc-support/result
   '';

pkgs/tools/misc/pandoc-lua-filters/default.nix

@@ -0,0 +1,33 @@
+{ stdenv
+, fetchFromGitHub
+}:
+
+stdenv.mkDerivation rec {
+  pname = "pandoc-lua-filters";
+  version = "2020-11-30";
+
+  src = fetchFromGitHub {
+    owner = "pandoc";
+    repo = "lua-filters";
+    rev = "v${version}";
+    sha256 = "HWBlmlIuJOSgRVrUmXOAI4XTxs1PbZhcwZgZFX0x2wM=";
+  };
+
+  dontBuild = true;
+
+  installPhase = ''
+    runHook preInstall
+
+    install -Dt $out/share/pandoc/filters **/*.lua
+
+    runHook postInstall
+  '';
+
+  meta = with stdenv.lib; {
+    description = "A collection of lua filters for pandoc";
+    homepage = "https://github.com/pandoc/lua-filters";
+    license = licenses.mit;
+    maintainers = with maintainers; [ jtojnar ];
+    platforms = platforms.all;
+  };
+}

pkgs/top-level/all-packages.nix

@@ -6378,6 +6378,8 @@ in
 
   pandoc = callPackage ../development/tools/pandoc { };
 
+  pandoc-lua-filters = callPackage ../tools/misc/pandoc-lua-filters { };
+
   pamtester = callPackage ../tools/security/pamtester { };
 
   paperless = callPackage ../applications/office/paperless { };