Does adding an enum variant break backwards compat?

[SUPERCILEX]

I just want to confirm: anything written as type A will be incompatible for reading as if it were type A'? Specifically for enum variants.

[finnbear]

Hello,

If you use the serde version (Serialize, Deserialize), then it's ok to add new variants at the end of your enum. Since bitcode can't know the total number of variants, they might as well have been there all along. In general, A and A' are compatible if what serde exposes is compatible.

If you use the derive version (Encode, Decode), which does know exactly which variants exist, then there is a high chance (and you must assume) that compatibility is broken. As a reward, enum's (among other things) take fewer bits than with serde.

[SUPERCILEX]

That's great to know, thanks! Can this (and anything else compatibility related) be documented? Happy to close this issue, but it'd be nice to have this stuff in the readme and crate docs.

[SUPERCILEX]

Actually, can I turn this into a feature request? I'd like to be able to specify the number of bits to reserve for an enum so I can choose how many I want to have for future compat. Really the setting should be "number of available variants" and in the backend it rounds up to a power of two or does something smarter.

[finnbear]

Can this (and anything else compatibility related) be documented?

This is not a "feature" we want to advertise. bitcode is not intended for compatibility when changing types or versions. If and when serde allows knowing the total number of enum variants, we'll optimize bitcode and remove this "feature."

(the existence of this issue - even after it is closed - serves as a small amount of searchable documentation, which is probably enough)

Actually, can I turn this into a feature request?

Unfortunately the ability to reserve enum variants is contingent on a few assumptions about how bitcode would organize data. A future version of bitcode might need to know the size/alignment/etc. of all variants or the enum itself, which wouldn't be known when reserving variants. We have an internal project that completely changes those assumptions and, while we might release it under a different name, we don't want to overconstrain bitcode's implementation either.

[SUPERCILEX]

bitcode is not intended for compatibility when changing types or versions

This is what should be documented then. Also when you say versions, you mean major versions right?

[finnbear]

Also when you say versions, you mean major versions right?

Yes, e.g. 0.4.0 to 0.5.0 or 1.0.0 to 2.0.0. Not minor/patch changes.

[finnbear]

Also, I talked with @caibear and another workaround (for Encode and Decode) is to add some placeholder variants for future use:

#[derive(Encode, Decode)]
enum Extensible {
    A,
    B(String),
    #[doc(hidden)]
    Placeholder1,
    #[doc(hidden)]
    Placeholder2,
}

Then, as long as you never use the placeholders, you can change their definition to be a tuple or struct variant.

[SUPERCILEX]

Clever!

can change their definition to be a tuple or struct variant

Is this guaranteed to always work? If so, that's good enough for me.

[finnbear]

Is this guaranteed to always work? If so, that's good enough for me.

Probably, unless we need to deprecate it in a major version (in which case you would have to break compatibility anyway by upgrading if you needed to upgrade).

[SUPERCILEX]

That's fine, thanks!