contrib/docker_notes.md: add notes re debian apt mirror, and envvars

related https://github.com/spesmilo/electrum/issues/8496

contrib/android/Readme.md

@@ -15,7 +15,9 @@ similar system.
 
 1. Install Docker
 
-    See `contrib/docker_notes.md`.
+    See [`contrib/docker_notes.md`](../docker_notes.md).
+
+    (worth reading even if you already have docker)
 
 2. Build binaries
 
@@ -27,7 +29,7 @@ similar system.
 
     If you want reproducibility, try instead e.g.:
     ```
-    $ ELECBUILD_COMMIT=HEAD ELECBUILD_NOCACHE=1 ./build.sh qml all release-unsigned
+    $ ELECBUILD_COMMIT=HEAD ./build.sh qml all release-unsigned
     ```
 
 3. The generated binary is in `./dist`.

contrib/build-linux/appimage/README.md

@@ -14,7 +14,9 @@ see [issue #5159](https://github.com/spesmilo/electrum/issues/5159).
 
 1. Install Docker
 
-    See `contrib/docker_notes.md`.
+    See [`contrib/docker_notes.md`](../../docker_notes.md).
+
+    (worth reading even if you already have docker)
 
 2. Build binary
 
@@ -23,7 +25,7 @@ see [issue #5159](https://github.com/spesmilo/electrum/issues/5159).
     ```
     If you want reproducibility, try instead e.g.:
     ```
-    $ ELECBUILD_COMMIT=HEAD ELECBUILD_NOCACHE=1 ./build.sh
+    $ ELECBUILD_COMMIT=HEAD ./build.sh
     ```
 
 3. The generated binary is in `./dist`.

contrib/build-linux/sdist/README.md

@@ -19,7 +19,9 @@ the source-only one, also includes:
 
 1. Install Docker
 
-    See `contrib/docker_notes.md`.
+    See [`contrib/docker_notes.md`](../../docker_notes.md).
+
+    (worth reading even if you already have docker)
 
 2. Build tarball
 

contrib/build-wine/README.md

@@ -8,7 +8,9 @@ similar system.
 
 1. Install Docker
 
-    See `contrib/docker_notes.md`.
+    See [`contrib/docker_notes.md`](../docker_notes.md).
+
+    (worth reading even if you already have docker)
 
     Note: older versions of Docker might not work well
     (see [#6971](https://github.com/spesmilo/electrum/issues/6971)).
@@ -21,7 +23,7 @@ similar system.
     ```
     If you want reproducibility, try instead e.g.:
     ```
-    $ ELECBUILD_COMMIT=HEAD ELECBUILD_NOCACHE=1 ./build.sh
+    $ ELECBUILD_COMMIT=HEAD ./build.sh
     ```
 
 3. The generated binaries are in `./contrib/build-wine/dist`.

contrib/docker_notes.md

@@ -1,4 +1,28 @@
-# Notes about using Docker in the build scripts
+# Using the build scripts
+
+Most of our build scripts are docker-based.
+(All, except the macOS build, which is a separate beast and always has to be special-cased
+at the cost of significant maintenance burden...)
+
+Typically, the build flow is:
+
+- build a docker image, based on debian
+  - the apt sources mirror used is `snapshot.debian.org`
+    - (except for the source tarball build, which is simple enough not to need this)
+    - this helps with historical reproducibility
+    - note that `snapshot.debian.org` is often slow and sometimes keeps timing out :/
+      (see #8496)
+      - a potential alternative would be `snapshot.notset.fr`, but that mirror is missing
+        e.g. `binary-i386`, which is needed for the wine/windows build.
+    - if you are just trying to build for yourself and don't need reproducibility,
+      you can just switch back to the default debian apt sources mirror.
+  - docker caches the build (locally), and so this step only needs to be rerun
+    if we update the Dockerfile. This caching happens automatically and by default.
+    - you can disable the caching by setting envvar `ELECBUILD_NOCACHE=1`. See below.
+- create a docker container from the image, and build the final binary inside the container
+
+
+## Notes about using Docker
 
 - To install Docker:
 
@@ -19,3 +43,26 @@
   ```
   (and then reboot or similar for it to take effect)
 
+
+## Environment variables
+
+- `ELECBUILD_COMMIT`
+
+    When unset or empty, we build directly from the local git clone. These builds
+    are *not* reproducible.
+
+    When non-empty, it should be set to a git ref. We will create a fresh git clone
+    checked out at that reference in `/tmp/electrum_build/`, and build there.
+
+- `ELECBUILD_NOCACHE=1`
+
+    A non-empty value forces a rebuild of the docker image.
+
+    Before we started using `snapshot.debian.org` for apt sources,
+    setting this was necessary to properly test historical reproducibility.
+    (we were version-pinning packages installed using `apt`, but it was not realistic to
+     version-pin all transitive dependencies, and sometimes an update of those resulted in
+     changes to our binary builds)
+
+    I think setting this is no longer necessary for building reproducibly.
+