diff options
author | Pol Dellaiera <pol.dellaiera@protonmail.com> | 2023-10-28 18:43:19 +0200 |
---|---|---|
committer | Pol Dellaiera <pol.dellaiera@protonmail.com> | 2023-10-29 11:16:16 +0100 |
commit | 036c5cb9ded6aceebee1fc507223a01603dd9310 (patch) | |
tree | 81cd7adacc518cac7446c4510dc9e9824ac640d5 /.github | |
parent | 5bd399713181bda23aa016ba06a5de069ec6c40f (diff) | |
download | nixpkgs-036c5cb9ded6aceebee1fc507223a01603dd9310.tar nixpkgs-036c5cb9ded6aceebee1fc507223a01603dd9310.tar.gz nixpkgs-036c5cb9ded6aceebee1fc507223a01603dd9310.tar.bz2 nixpkgs-036c5cb9ded6aceebee1fc507223a01603dd9310.tar.lz nixpkgs-036c5cb9ded6aceebee1fc507223a01603dd9310.tar.xz nixpkgs-036c5cb9ded6aceebee1fc507223a01603dd9310.tar.zst nixpkgs-036c5cb9ded6aceebee1fc507223a01603dd9310.zip |
doc: update r-b issue template
Diffstat (limited to '.github')
-rw-r--r-- | .github/ISSUE_TEMPLATE/unreproducible_package.md | 72 |
1 files changed, 64 insertions, 8 deletions
diff --git a/.github/ISSUE_TEMPLATE/unreproducible_package.md b/.github/ISSUE_TEMPLATE/unreproducible_package.md index 13988026f8d..8046e809a21 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 +In the following steps, replace `<package>` with the canonical name of the +package. + +#### 1. Build the package + +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-build '<nixpkgs>' -A ... && nix-build '<nixpkgs>' -A ... --check --keep-failed +nix-build '<nixpkgs>' -A <package> && nix-build '<nixpkgs>' -A <package> --check --keep-failed ``` -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. +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>) +``` -To view the build log of the build that produced the artifact in the binary cache: +Or with the new command line style: ``` -nix-store --read-log $(nix-instantiate '<nixpkgs>' -A ...) +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) |