go/analysis: document need for deterministic Fact encoding

adonovan · adonovan · commit 43cce678a193 · 2022-06-06T15:25:04.000Z
Change-Id: I5a1b537f5ba14405fa1e9916b6d63e4fc7e5db45 Reviewed-on: https://go-review.googlesource.com/c/tools/+/410364 Reviewed-by: Hyang-Ah Hana Kim <hyangah@gmail.com>
diff --git a/go/analysis/doc.go b/go/analysis/doc.go
@@ -241,6 +241,9 @@ Consequently, Facts must be serializable. The API requires that drivers
 use the gob encoding, an efficient, robust, self-describing binary
 protocol. A fact type may implement the GobEncoder/GobDecoder interfaces
 if the default encoding is unsuitable. Facts should be stateless.
+Because serialized facts may appear within build outputs, the gob encoding
+of a fact must be deterministic, to avoid spurious cache misses in
+build systems that use content-addressable caches.
 
 The Pass type has functions to import and export facts,
 associated either with an object or with a package:
