From c4b6b2f12462c1f2648c66f1895cfd599c6d4f05 Mon Sep 17 00:00:00 2001
From: Thierry Laurion <insurgo@riseup.net>
Date: Tue, 4 Aug 2026 19:43:45 -0400
Subject: [PATCH] doc/reproducible-builds.md: clarify same-commit vs
 different-commit verification

Remove stale claim that warm builds produce partial hashes.txt
(FORCE on modules.cpio ensures completeness).  Separate verification
into Same commit (everything should match) and Different commits
(ROM always differs due to GIT_HASH in /etc/config).  Drop
real.gitclean_keep_packages reference.

Signed-off-by: Thierry Laurion <insurgo@riseup.net>
---
 doc/reproducible-builds.md | 45 +++++++++++++++++---------------------
 1 file changed, 20 insertions(+), 25 deletions(-)

diff --git a/doc/reproducible-builds.md b/doc/reproducible-builds.md
index 3a2aabe67..6d1a0a8a7 100644
--- a/doc/reproducible-builds.md
+++ b/doc/reproducible-builds.md
@@ -112,11 +112,8 @@ fetch_source_archive.sh.
 ## Verifying ROM Reproducibility
 
 ### Prerequisites
-- Same git commit on both CI and local
+- Same git commit on both CI and local (different commits produce different ROMs — see below)
 - Build with `docker_repro.sh` locally (same Docker image as CI)
-- For a complete `hashes.txt`, use `real.gitclean_keep_packages` first.
-  Warm (cached) builds produce partial `hashes.txt` — only rebuilt targets
-  re-append their hashes.
 
 ### Understanding hashes.txt
 
@@ -139,38 +136,36 @@ separated by `-----` lines:
 -----
 ```
 
-### GIT_HASH in /etc/config
+### Same commit: everything should match
 
-`tools.cpio` contains `./etc/config`, which embeds `GIT_HASH` from `git rev-parse HEAD`
-(in the `/etc/config` generation rule).  Every commit changes `GIT_HASH`, so `./etc/config` differs
-between ANY two commits.  This cascades: `./etc/config` → `tools.cpio` →
-`initrd.cpio.xz` → ROM.
+When CI and local build the **same git commit**, the ROM hash should match.
+If it does, the build is reproducible:
 
-When `./etc/config` is the **only** differing file inside `tools.cpio`, the
-build is still reproducible — all binaries (busybox, kexec, gpg, etc.) are
-byte-identical.  A binary mismatch (e.g. `./bin/busybox`) is the actual
-reproducibility bug to investigate.
-
-### Steps
-
-1. Build locally and download CI `hashes.txt` for the same commit.
-
-2. Compare ROM hashes — if they match, the build is reproducible. Done.
 ```bash
 grep '\.rom' /tmp/ci-hashes.txt build/x86/EOL_t480-hotp-maximized/hashes.txt
 ```
 
-3. If the ROM differs, step down: `initrd.cpio.xz`/`bzImage` → `tools.cpio` →
+If the ROM differs, step down: `initrd.cpio.xz` → `tools.cpio` →
 individual files.  The innermost differing file (e.g. `./bin/busybox`) is the
 root cause — fix it and the cascade resolves.  `hashes.txt` records every file
-at every level, so no diffoscope is needed until you've identified what differs.
+at every level so no diffoscope is needed until you've identified what differs.
 
-4. For a comprehensive check:
+For a comprehensive same-commit check:
 ```bash
 diff <(grep '^[0-9a-f]\{64\}' /tmp/ci-hashes.txt | awk '{print $1}' | sort) \
      <(grep '^[0-9a-f]\{64\}' build/x86/EOL_t480-hotp-maximized/hashes.txt | awk '{print $1}' | sort)
 ```
+Zero output = all hashes match.
 
-`./etc/config` inside `tools.cpio` always differs between commits (contains
-`GIT_HASH`).  Its cascade through `tools.cpio`/`initrd.cpio.xz`/ROM is expected;
-only a binary mismatch is a reproducibility bug.
+### Different commits: ROMs always differ
+
+`tools.cpio` contains `./etc/config`, which embeds `GIT_HASH` from
+`git rev-parse HEAD`.  Every commit changes `GIT_HASH`, so `./etc/config`
+differs between ANY two commits.  This cascades: `./etc/config` → `tools.cpio`
+→ `initrd.cpio.xz` → ROM.  The ROM hash WILL differ between different commits —
+this is expected.
+
+When `./etc/config` is the **only** differing file inside `tools.cpio`, the
+build is still reproducible — all binaries (busybox, kexec, gpg, etc.) are
+byte-identical.  A binary mismatch is the actual reproducibility bug to
+investigate.