docs: warn about keeping compiler versions consistent across upgrades (#29547)

* docs: warn about keeping compiler versions consistent across upgrades

* docs: note constructor and feature stability, not just checksums

Signed-off-by: Matt Van Horn <455140+mvanhorn@users.noreply.github.com>

---------

Signed-off-by: Matt Van Horn <455140+mvanhorn@users.noreply.github.com>
Co-authored-by: Matt Van Horn <455140+mvanhorn@users.noreply.github.com>
Co-authored-by: IGI-111 <igi-111@protonmail.com>

Author: mvanhorn

documentation/guides/program_upgradability.md

@@ -134,6 +134,27 @@ constructor:
     position end;
 ```
 
+### Warning: Keep Compiler Versions Consistent
+
+Checksum-governed upgrades are bytecode-sensitive. Do not assume bytecode is stable across Leo compiler versions: different compiler versions can produce different bytecode for identical source, which can cause a checksum-governed upgrade to fail.
+
+Version consistency matters beyond checksums, though. A program's constructor cannot change between upgrades, and compiler behavior or supported features can change (or even break) across versions. Building every edition with the same pinned toolchain avoids both bytecode drift and subtle semantic differences a different compiler version could introduce.
+
+Pin the Leo compiler version used for the initial deployment and all subsequent upgrades. Before deploying or approving an upgrade, check the local toolchain:
+
+```bash
+leo --version
+```
+
+To inspect the source currently deployed on the network, query the program. Use `--edition <N>` when you need to inspect a specific edition:
+
+```bash
+leo query program <NAME>
+leo query program <NAME> --edition <N>
+```
+
+The query returns deployed source; it does not print the compiler version. Use it with your pinned toolchain record and rebuild with the same Leo version to avoid bytecode drift.
+
 ### Pattern 4: Custom Logic (Time-lock Example)
 
 **Goal:** Enforce a time delay before an upgrade is allowed. No pre-defined mode is available for this so we'll have to write our own upgrade policy