From 2fbedb9402972f76c8eb6221a88db7ba073df8fc Mon Sep 17 00:00:00 2001
From: Philip Taron <philip.taron@gmail.com>
Date: Wed, 3 Sep 2025 06:35:01 -0700
Subject: [PATCH] ci: have `eval.full` return the report as displayed in CI

Update the README.md to document what gets returned.
We might in the future split these up into other attrsets but I don't see a usecase for that at the moment.

(cherry picked from commit 07916fc3fd84832119cbc6cd0d70ad9a0fe7c347)
---
 ci/eval/README.md   |  3 +++
 ci/eval/default.nix | 17 ++++++++++++++---
 2 files changed, 17 insertions(+), 3 deletions(-)

diff --git a/ci/eval/README.md b/ci/eval/README.md
index 57cde7c65fe9..2e7ae0d3876b 100644
--- a/ci/eval/README.md
+++ b/ci/eval/README.md
@@ -43,3 +43,6 @@ nix-build ci -A eval.full --arg baseline $BASELINE
 ```
 
 Keep in mind to otherwise pass the same set of arguments for both commands (`evalSystems`, `quickTest`, `chunkSize`).
+Running this command will evaluate the difference between the baseline statistics and the ones at the time of running the command.
+From that difference, it will produce a human-readable report in `$out/step-summary.md`.
+If no packages were added or removed, then performance statistics will also be generated as part of this report.
diff --git a/ci/eval/default.nix b/ci/eval/default.nix
index a379594dbc6d..c7310a5052d0 100644
--- a/ci/eval/default.nix
+++ b/ci/eval/default.nix
@@ -267,6 +267,15 @@ let
       chunkSize ? 5000,
       quickTest ? false,
       baseline,
+      # Which maintainer should be considered the author?
+      # Defaults to nixpkgs-ci which is not a maintainer and skips the check.
+      githubAuthorId ? "nixpkgs-ci",
+      # What files have been touched? Defaults to none; use the expression below to calculate it.
+      # ```
+      # git diff --name-only --merge-base master HEAD \
+      #   | jq --raw-input --slurp 'split("\n")[:-1]' > touched-files.json
+      # ```
+      touchedFilesJson ? builtins.toFile "touched-files.json" "[ ]",
     }:
     let
       diffs = symlinkJoin {
@@ -282,10 +291,12 @@ let
           }
         ) evalSystems;
       };
+      comparisonReport = compare {
+        combinedDir = combine { diffDir = diffs; };
+        inherit touchedFilesJson githubAuthorId;
+      };
     in
-    combine {
-      diffDir = diffs;
-    };
+    comparisonReport;
 
 in
 {