Add best pratice for how to check in generated files (#16405)

Best practice here is to have a test that checks if the generated file
matches, but that wasn't documented anywhere.

Author: epage

src/doc/src/reference/build-script-examples.md

@@ -86,6 +86,13 @@ There’s a couple of points of note here:
   such crate as a dependency, because there's an *implicit* invariant that
   sources in `.cargo/registry` should be immutable. `cargo` won't allow such
   scripts when packaging.
+  * Sometimes, projects want to check in a generated file, and treat it as
+    source code. However, in this case, the file shouldn't be generated from
+    `build.rs`. Instead, have a test or similar which checks that the file
+    precisely matches the generated version *and fails if the result doesn't
+    match*, and run that test as part of your CI. (The test can generate a
+    temporary file to compare to, and if you want to update the generated file,
+    you can replace the checked-in file with that temporary file.)
 * This script is relatively simple as it just writes out a small generated file.
   One could imagine that other more complex operations could take place such as
   generating a Rust module from a C header file or another language definition,