[MLIR] Document the stability and versioning aspect of the Bytecode

[joker-eph]

See the two RFCs:

https://discourse.llvm.org/t/rfc-mlir-bytecode-a-stable-serialization-format/71062
https://discourse.llvm.org/t/rfc-ir-versioning/5893

[llvmbot]

@llvm/pr-subscribers-mlir

Author: Mehdi Amini (joker-eph)

Changes

See the two RFCs:

https://discourse.llvm.org/t/rfc-mlir-bytecode-a-stable-serialization-format/71062
https://discourse.llvm.org/t/rfc-ir-versioning/5893

---

Full diff: https://github.com/llvm/llvm-project/pull/81969.diff

1 Files Affected:

• (modified) mlir/docs/BytecodeFormat.md (+19)

diff --git a/mlir/docs/BytecodeFormat.md b/mlir/docs/BytecodeFormat.md
index 589671ee6df3ea..869b2d8f0a00b6 100644
--- a/mlir/docs/BytecodeFormat.md
+++ b/mlir/docs/BytecodeFormat.md
@@ -1,6 +1,25 @@
 # MLIR Bytecode Format
 
 This documents describes the MLIR bytecode format and its encoding.
+This format is versioned and stable: we don't plan to ever break
+compatibility, that is a dialect should be able to deserialize and
+older bytecode. Similarly, we support back-deployment we an older
+version of the format can be targetted.
+
+That said, it is important to realize that the promises of the
+bytecode format are made assuming immutable dialects: the format
+allows backward and forward compatibility, but only when nothing
+in a dialect changes (operations, types, attributes definitions).
+
+A dialect can opt-in to handle its own versioning through the
+`BytecodeDialectInterface`. Some hooks are exposed to the dialect
+to allow managing a version encoded into the bytecode file. The
+version is loaded lazily and allows to retrieve the version
+information while decoding the input IR, and gives an opportunity
+to each dialect for which a version is present to perform IR
+upgrades post-parsing through the `upgradeFromVersion` method.
+There is no restriction on what kind of information a dialect
+is allowed to encode to model its versioning
 
 [TOC]