ESP IDF has a source backwards compatibility policy that does allow adding new members to C structs and enums, where this is not considered a backwards incompatible change.
To model this in the esp-idf-hal and esp-idf-svc crates we need to do roughly the following:
For Rust struct/enum wrappers of "raw" esp-idf-sys types
Annotate these with #[non_exhaustive]; this way, the user code would be forced to destructure such structs with .. and to have a _ => "match all" on such enums, which - in turn - would allow us to add new members to these types without this being a breaking change for the user
For structs specifically - implement a public constructor function (as #[non_exhaustive] structs cannot be constructed directly by the user) and optionally - a builder pattern (to be decided)
For raw C enums from esp-idf-sys's bindings
When converting these to the actual Rust enums, have a "catch-all" non-panicking _ => leg in the match statement to convert any potentially new yet unmapped values to a generic Rust enum Other or Unknown value (which needs to be introduced if it is not already there). Ideally, this value should carry the raw esp-idf-sys constant.
==========
The above would be a one-time breaking change but it would allow us to model member addition to configuration types as a non-breaking change in future.
ESP IDF has a source backwards compatibility policy that does allow adding new members to C structs and enums, where this is not considered a backwards incompatible change.
To model this in the
esp-idf-hal
andesp-idf-svc
crates we need to do roughly the following:For Rust struct/enum wrappers of "raw"
esp-idf-sys
types#[non_exhaustive]
; this way, the user code would be forced to destructure such structs with..
and to have a_ =>
"match all" on such enums, which - in turn - would allow us to add new members to these types without this being a breaking change for the user#[non_exhaustive]
structs cannot be constructed directly by the user) and optionally - a builder pattern (to be decided)For raw C enums from
esp-idf-sys
's bindingsWhen converting these to the actual Rust enums, have a "catch-all" non-panicking
_ =>
leg in thematch
statement to convert any potentially new yet unmapped values to a generic Rust enumOther
orUnknown
value (which needs to be introduced if it is not already there). Ideally, this value should carry the rawesp-idf-sys
constant.==========
The above would be a one-time breaking change but it would allow us to model member addition to configuration types as a non-breaking change in future.