From 036c5cb9ded6aceebee1fc507223a01603dd9310 Mon Sep 17 00:00:00 2001
From: Pol Dellaiera <pol.dellaiera@protonmail.com>
Date: Sat, 28 Oct 2023 18:43:19 +0200
Subject: [PATCH] doc: update r-b issue template

---
 .../ISSUE_TEMPLATE/unreproducible_package.md  | 76 ++++++++++++++++---
 1 file changed, 66 insertions(+), 10 deletions(-)

diff --git a/.github/ISSUE_TEMPLATE/unreproducible_package.md b/.github/ISSUE_TEMPLATE/unreproducible_package.md
index 13988026f8d7..8046e809a214 100644
--- a/.github/ISSUE_TEMPLATE/unreproducible_package.md
+++ b/.github/ISSUE_TEMPLATE/unreproducible_package.md
@@ -7,25 +7,81 @@ assignees: ''
 
 ---
 
-Building this package twice does not produce the bit-by-bit identical result each time, making it harder to detect CI breaches. You can read more about this at https://reproducible-builds.org/ .
+<!--
+Hello dear reporter,
 
-Fixing bit-by-bit reproducibility also has additional advantages, such as avoiding hard-to-reproduce bugs, making content-addressed storage more effective and reducing rebuilds in such systems.
+Thank you for bringing attention to this issue. Your insights are valuable to
+us, and we appreciate the time you took to document the problem.
+
+I wanted to kindly point out that in this issue template, it would be beneficial
+to replace the placeholder `<package>` with the actual, canonical name of the
+package you're reporting the issue for. Doing so will provide better context and
+facilitate quicker troubleshooting for anyone who reads this issue in the
+future.
+
+Best regards
+-->
+
+Building this package multiple times does not yield bit-by-bit identical
+results, complicating the detection of Continuous Integration (CI) breaches. For
+more information on this issue, visit
+[reproducible-builds.org](https://reproducible-builds.org/).
+
+Fixing bit-by-bit reproducibility also has additional advantages, such as
+avoiding hard-to-reproduce bugs, making content-addressed storage more effective
+and reducing rebuilds in such systems.
 
 ### Steps To Reproduce
 
-```
-nix-build '<nixpkgs>' -A ... && nix-build '<nixpkgs>' -A ... --check --keep-failed
-```
+In the following steps, replace `<package>` with the canonical name of the
+package.
 
-If this command completes successfully, no differences where found. However, when it ends in `error: derivation '<X>' may not be deterministic: output '<Y>' differs from '<Z>'`, you can use `diffoscope <Y> <Z>` to analyze the differences in the output of the two builds.
+#### 1. Build the package
 
-To view the build log of the build that produced the artifact in the binary cache:
+This step will build the package. Specific arguments are passed to the command
+to keep the build artifacts so we can compare them in case of differences.
+
+Execute the following command:
 
 ```
-nix-store --read-log $(nix-instantiate '<nixpkgs>' -A ...)
+nix-build '<nixpkgs>' -A <package> && nix-build '<nixpkgs>' -A <package> --check --keep-failed
+```
+
+Or using the new command line style:
+
+```
+nix build nixpkgs#<package> && nix build nixpkgs#<package> --rebuild --keep-failed
+```
+
+#### 2. Compare the build artifacts
+
+If the previous command completes successfully, no differences were found and
+there's nothing to do, builds are reproducible.
+If it terminates with the error message `error: derivation '<X>' may not be
+deterministic: output '<Y>' differs from '<Z>'`, use `diffoscope` to investigate
+the discrepancies between the two build outputs. You may need to add the
+`--exclude-directory-metadata recursive` option to ignore files and directories
+metadata (*e.g. timestamp*) differences.
+
+```
+nix run nixpkgs#diffoscopeMinimal -- --exclude-directory-metadata recursive <Y> <Z>
+```
+
+#### 3. Examine the build log
+
+To examine the build log, use:
+
+```
+nix-store --read-log $(nix-instantiate '<nixpkgs>' -A <package>)
+```
+
+Or with the new command line style:
+
+```
+nix log $(nix path-info --derivation nixpkgs#<package>)
 ```
 
 ### Additional context
 
-(please share the relevant fragment of the diffoscope output here,
-and any additional analysis you may have done)
+(please share the relevant fragment of the diffoscope output here, and any
+additional analysis you may have done)