.github/ISSUE_TEMPLATE/unreproducible_package.md

   1 ---
   2 name: Unreproducible package
   3 about: A package that does not produce a bit-by-bit reproducible result each time it is built
   4 title: ''
   5 labels: [ '0.kind: enhancement', '6.topic: reproducible builds' ]
   6 assignees: ''
   7
   8 ---
   9
  10 <!--
  11 Hello dear reporter,
  12
  13 Thank you for bringing attention to this issue. Your insights are valuable to
  14 us, and we appreciate the time you took to document the problem.
  15
  16 I wanted to kindly point out that in this issue template, it would be beneficial
  17 to replace the placeholder `<package>` with the actual, canonical name of the
  18 package you're reporting the issue for. Doing so will provide better context and
  19 facilitate quicker troubleshooting for anyone who reads this issue in the
  20 future.
  21
  22 Best regards
  23 -->
  24
  25 Building this package multiple times does not yield bit-by-bit identical
  26 results, complicating the detection of Continuous Integration (CI) breaches. For
  27 more information on this issue, visit
  28 [reproducible-builds.org](https://reproducible-builds.org/).
  29
  30 Fixing bit-by-bit reproducibility also has additional advantages, such as
  31 avoiding hard-to-reproduce bugs, making content-addressed storage more effective
  32 and reducing rebuilds in such systems.
  33
  34 ### Steps To Reproduce
  35
  36 In the following steps, replace `<package>` with the canonical name of the
  37 package.
  38
  39 #### 1. Build the package
  40
  41 This step will build the package. Specific arguments are passed to the command
  42 to keep the build artifacts so we can compare them in case of differences.
  43
  44 Execute the following command:
  45
  46 ```
  47 nix-build '<nixpkgs>' -A <package> && nix-build '<nixpkgs>' -A <package> --check --keep-failed
  48 ```
  49
  50 Or using the new command line style:
  51
  52 ```
  53 nix build nixpkgs#<package> && nix build nixpkgs#<package> --rebuild --keep-failed
  54 ```
  55
  56 #### 2. Compare the build artifacts
  57
  58 If the previous command completes successfully, no differences were found and
  59 there's nothing to do, builds are reproducible.
  60 If it terminates with the error message `error: derivation '<X>' may not be
  61 deterministic: output '<Y>' differs from '<Z>'`, use `diffoscope` to investigate
  62 the discrepancies between the two build outputs. You may need to add the
  63 `--exclude-directory-metadata recursive` option to ignore files and directories
  64 metadata (*e.g. timestamp*) differences.
  65
  66 ```
  67 nix run nixpkgs#diffoscopeMinimal -- --exclude-directory-metadata recursive <Y> <Z>
  68 ```
  69
  70 #### 3. Examine the build log
  71
  72 To examine the build log, use:
  73
  74 ```
  75 nix-store --read-log $(nix-instantiate '<nixpkgs>' -A <package>)
  76 ```
  77
  78 Or with the new command line style:
  79
  80 ```
  81 nix log $(nix path-info --derivation nixpkgs#<package>)
  82 ```
  83
  84 ### Additional context
  85
  86 (please share the relevant fragment of the diffoscope output here, and any
  87 additional analysis you may have done)