Semvers below 1.0.0

The Cargo Book says this about crates with semvers less than 1.0.0:

Before you reach 1.0.0, anything goes, but if you make breaking changes, increment the minor version. In Rust, breaking changes include adding fields to structs or variants to enums.

What about structs or enums that aren't part of the public API? I presume I can freely add a variant to an enum that isn't exposed publicly without that being a breaking change.

Absolutely.

Indeed, private structs / enums, such as those used in private fields, do not affect the API of the crate, except for auto traits!

For instance, if you have

pub
struct PubStruct {
    pub
    pub_field: i32,

    private_field: PrivateStruct,
}

struct PrivateStruct {
    // fields to be added later
}

And then, for instance, decide to make PrivateStruct hold a Cell<bool>, it will be a breaking change since that will make PrivateStruct : !Sync which in turn will make PubStruct : !Sync, which is part of the public API of PubStruct.

(This, by the way, is the main reason behind Copy not being an auto-trait)

5 Likes

FYI: RFC 1105 (referred by the cargo book) and Future proofing - Rust API Guidelines are useful resources about crate compatibility and future-proofing.

2 Likes

Aha! So yes...but also tricky. :slight_smile:

Thanks very much!