1The `schema.fbs` file in this directory describes the 2[Flatbuffers](https://google.github.io/flatbuffers/) schema used to serialize 3ExecuTorch programs. 4 5The `scalar_type.fbs` file contains schema for scalar types. 6 7## Rules to ensure forward/backward compatibility 8 9A serialized program never knows which version of the code will try to read it. 10It's important that old code can read serialized programs generated by new code 11(forward compatibility; FC), and that new code can read serialized programs 12generated by old code (backward compatibility; BC). 13 14For background on the rules below, see the Flatbuffers document [Writing a 15schema](https://google.github.io/flatbuffers/md__schemas.html), especially the 16"Tables" and "Schema evolution examples" sections. 17 18To ensure binary FC/BC: 19 20- Use `table`, not `struct`, for structured data. 21 - `struct` cannot handle optional fields; changes to `struct` are typically 22 not FC/BC. 23- When adding new fields, do not modify the ID of existing fields. 24 - The easiest way to do this is to add new fields to the bottom of a `table`. 25 - If it's important to reorder the declaration of fields for readability, 26 all fields in the `table` must be explicitly annotated with `(ID: #)` fields 27 that preserve their original zero-based indices. 28- Fields must never be removed; they can only be deprecated using the 29 `(deprecated)` annotation. 30- Semantics for existing fields must not change without carefully auditing older 31 versions of the code to understand the implications. 32- Default values for fields must be very carefully managed. 33 - Ideally, the default value for a field will never change. 34 - If they do change, audit old and new code to understand the implications of 35 the change. 36 - Note that fields with unspecified defaults will default to the zero value of 37 their types. 38- Ideally the types of fields must not change. If they do, ensure that they are 39 compatible: e.g., a `uint` could change to `int` if we are confident that no 40 program in existence stored a value in that field with the most significant 41 bit set. 42 43Note that these rules do not ensure source code FC/BC. E.g., deprecating a field 44will tell Flatbuffer's `flatc` to stop generating getters/setters for it, so any 45code using those functions will fail to build, and will need to be fixed. 46 47However, this serialization format and the Flatbuffer types that are generated 48from it are private to ExecuTorch, so we do not need to worry about updating 49external client code when the Flatbuffer API changes. This also means that we 50can more easily upgrade to new versions of the Flatbuffers tools/library. 51 52If we are forced to make a FC/BC-breaking change, it may make sense to create a 53new `.fbs` file with a different `file_identifier`, and adding higher-level 54logic to check the file magic before parsing the binary file with one schema or 55the other. 56