From 6036e3d8056b83bcebf1117e9884f30c39c2a3ef Mon Sep 17 00:00:00 2001
From: Hector Santos <netsirius@gmail.com>
Date: Sun, 19 Jul 2026 16:58:16 +0200
Subject: [PATCH] docs: update CONTRIBUTING.md with flatbuffers regeneration
 instructions #4747

---
 CONTRIBUTING.md |  1 +
 rust/build.rs   | 31 ++++++++++++++++++++++++-------
 2 files changed, 25 insertions(+), 7 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 1d62852..42ae2b5 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -15,6 +15,7 @@ We welcome contributions to Freenet! Here's what you need to know.
 - Bug fixes should include a regression test that fails without the fix.
 - Run `cargo fmt`, `cargo clippy --all-targets`, and `cargo test` before pushing.
 - Keep PRs focused — one logical change per PR.
+- The flatbuffers bindings in `rust/src/generated/` are checked in and are the source of truth. A normal build does **not** regenerate them. If you edit a schema under `schemas/flatbuffers/`, regenerate with `REGEN_FLATBUFFERS=1 cargo build` and commit the `.fbs` and its regenerated `_generated.rs` together.
 
 ## AI-Assisted Contributions
 
diff --git a/rust/build.rs b/rust/build.rs
index df45757..35638a2 100644
--- a/rust/build.rs
+++ b/rust/build.rs
@@ -1,6 +1,21 @@
 use std::process::Command;
 
 fn main() {
+    // The checked-in files in src/generated are the source of truth; regenerating
+    // them on every build with the local flatc dirtied the tree (freenet-core#4747).
+    // After editing a schema, regenerate with `REGEN_FLATBUFFERS=1 cargo build`.
+    println!("cargo:rerun-if-env-changed=REGEN_FLATBUFFERS");
+    let regen = std::env::var("REGEN_FLATBUFFERS").unwrap_or_default();
+    if regen.is_empty() || regen == "0" {
+        return;
+    }
+
+    println!("cargo:rerun-if-changed=../schemas/flatbuffers/common.fbs");
+    println!("cargo:rerun-if-changed=../schemas/flatbuffers/client_request.fbs");
+    println!("cargo:rerun-if-changed=../schemas/flatbuffers/host_response.fbs");
+
+    // Regeneration was requested explicitly, so fail loudly rather than
+    // succeed with stale files.
     let status = Command::new("flatc")
         .arg("--rust")
         .arg("-o")
@@ -8,11 +23,13 @@ fn main() {
         .arg("../schemas/flatbuffers/common.fbs")
         .arg("../schemas/flatbuffers/client_request.fbs")
         .arg("../schemas/flatbuffers/host_response.fbs")
-        .status();
-    if let Err(err) = status {
-        println!("failed compiling flatbuffers schema: {err}");
-        println!("refer to https://github.com/google/flatbuffers to install the flatc compiler");
-    } else {
-        let _ = Command::new("cargo").arg("fmt").status();
-    }
+        .status()
+        .unwrap_or_else(|err| {
+            panic!(
+                "REGEN_FLATBUFFERS is set but flatc could not be run: {err}\n\
+                 refer to https://github.com/google/flatbuffers to install the flatc compiler"
+            )
+        });
+    assert!(status.success(), "flatc failed with {status}");
+    let _ = Command::new("cargo").arg("fmt").status();
 }