From 983bec568c38f099bb83286b4c84c1f50d0e735f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jalil=20David=20Salam=C3=A9=20Messina?=
 <jalil.salame@gmail.com>
Date: Thu, 19 Dec 2024 23:52:27 +0100
Subject: [PATCH] feat(comment): add some context on how to read the data

This should help them out to reduce the size.

Also rectify misunderstanding about NAR Size.
---
 comment_on_pr.sh | 27 +++++++++++++++++++++------
 1 file changed, 21 insertions(+), 6 deletions(-)

diff --git a/comment_on_pr.sh b/comment_on_pr.sh
index 8b394ad..7edb23f 100755
--- a/comment_on_pr.sh
+++ b/comment_on_pr.sh
@@ -41,15 +41,30 @@ markdown_from_report() {
 	cat <<-"EOF"
 		# Flake output sizes
 
-		- `Name`: the name of the package/configuration
-		- `Size`: the closure size (size on disk of the package/configuration)
-		- `NAR Size`: the size of the generated build instructions (Nix ARchive)
+		**Definitions:**
+
+		- `Name`: the name of the package/configuration.
+		- `Size`: the closure size (size on disk/NAR size + all transitive dependencies).
+		- `NAR Size`: the size of the build output (package without the dependencies).
+	EOF
+	if [ "${2+set}" = "set" ]; then
+		cat <<-"EOF"
+			- `[NAR] Size Change`: the amount changed compared to the main branch.
+		EOF
+	fi
+	cat <<-"EOF"
+
+		**Tips on reading this data:**
+
+		- For NixOS configurations you generally care only about the `Size` (closure size/size on disk).
+		  - Reduce the `Size` by disabling unneeded services/default packages.
+		- For Packages you care about both the `Size` and the `NAR Size`.
+		  - Reduce the `NAR Size` by reducing the size of the build outputs, e.g. don't copy unnecessary data to the $out dir, optimize binaries for size, etc.
+		  - Reduce the `Size` by reducing the dependencies (e.g. `buildInputs`).
+		  - Don't worry too much about size, some dependencies are deduplicated, e.g. `glibc` adds ~40MiB to the `Size`, but is generally shared by ~every binary on the system, so, chances are, you are already including it from somewhere else and statically linking with e.g. `musl` is not gonna improve things.
 	EOF
 
 	if [ "${2+set}" = "set" ]; then
-		cat <<-"EOF"
-			- `[NAR] Size Change`: the amount changed compared to the main branch
-		EOF
 		compare=$(jq --slurp --from-file "${GITHUB_ACTION_PATH:-.}/compare.jq" "$1" "$2")
 		if echo "$compare" | has_elements 'nixosConfigurations'; then
 			cat <<-"EOF"