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/ . + + +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 '' -A ... && nix-build '' -A ... --check --keep-failed -``` +In the following steps, replace `` with the canonical name of the +package. -If this command completes successfully, no differences where found. However, when it ends in `error: derivation '' may not be deterministic: output '' differs from ''`, you can use `diffoscope ` 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 '' -A ...) +nix-build '' -A && nix-build '' -A --check --keep-failed +``` + +Or using the new command line style: + +``` +nix build nixpkgs# && nix build nixpkgs# --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 '' may not be +deterministic: output '' differs from ''`, 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 +``` + +#### 3. Examine the build log + +To examine the build log, use: + +``` +nix-store --read-log $(nix-instantiate '' -A ) +``` + +Or with the new command line style: + +``` +nix log $(nix path-info --derivation nixpkgs#) ``` ### 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)