metropolis/handbook: document stamping
Change-Id: Id4ff51f7b0cb2e3969a18cd03ec31f4200def182
Reviewed-on: https://review.monogon.dev/c/monogon/+/4285
Reviewed-by: Tim Windelschmidt <tim@monogon.tech>
Tested-by: Jenkins CI
diff --git a/metropolis/handbook/src/ch05-01-checking-out-and-building.md b/metropolis/handbook/src/ch05-01-checking-out-and-building.md
new file mode 100644
index 0000000..29eb61d
--- /dev/null
+++ b/metropolis/handbook/src/ch05-01-checking-out-and-building.md
@@ -0,0 +1,14 @@
+# Checking out and building
+
+## Stamping
+
+The Metropolis OS image is stamped with info from the current git commit (commit hash, commit date and dirty flag).
+This is useful when the image is deployed, as you know exactly which version is running in your cluster.
+Each time you make a commit or change the dirty state during development, the stamping info changes, forcing a rebuild of the OS image.
+This rebuild is quite cheap, since no binaries are rebuilt.
+However, it does invalidate cached test results for all end-to-end tests which depend on the OS image.
+If you prefer, you can disable stamping.
+
+To disable stamping, pass the `--config=nostamp` flag.
+Note that the builtin Bazel flag `--nostamp` does not work in this repo.
+To set this flag for all builds, create the file `.bazelrc.user` in the repository root with content `build --config=nostamp`.