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
   '';