From 340cc7d9122134e53c2c90abff31af64d2d7036c Mon Sep 17 00:00:00 2001
From: Alex Pyrgiotis <alex.p@freedom.press>
Date: Tue, 10 Dec 2024 12:46:16 +0200
Subject: [PATCH] FIXUP: Explain why image caching is bad for release artifacts

---
 docs/developer/doit.md | 7 +++++++
 pyproject.toml         | 3 ++-
 2 files changed, 9 insertions(+), 1 deletion(-)

diff --git a/docs/developer/doit.md b/docs/developer/doit.md
index cacfb844d..a461d967a 100644
--- a/docs/developer/doit.md
+++ b/docs/developer/doit.md
@@ -51,6 +51,13 @@ doit <task>
   use_cache = true
   ```
 
+  > [!WARNING]
+  > Using caching may speed up image builds, but is not suitable for release
+  > artifacts. The ID of our base container image (Alpine Linux) does not change
+  > that often, but its APK package index does. So, if we use caching, we risk
+  > skipping the `apk upgrade` layer and end up with packages that are days
+  > behind.
+
 * You can pass the following environment variables to the script, in order to
   affect some global parameters:
   - `CONTAINER_RUNTIME`: The container runtime to use. Either `podman` (default)
diff --git a/pyproject.toml b/pyproject.toml
index 9945c35fd..66192ba90 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -71,7 +71,8 @@ follow_links = false
 verbosity = 3
 
 [tool.doit.tasks.build_image]
-# DO NOT change this to 'true' for release artifacts.
+# DO NOT change this to 'true' for release artifacts, else we risk building
+# images that are a few days behind. See also: docs/developer/doit.md
 use_cache = false
 
 [build-system]