api-guidelines
api-guidelines copied to clipboard
rust-lang
C-STRUCT-PRIVATE guideline incomplete
The C-STRUCT-PRIVATE recommendation talks about a single struct field being public or private.
It does not mention what happens when all fields of a struct are public, e.g., in that particular case, users can exhaustively pattern-match the struct, which means that adding a new field to the struct, even a private one, is a breaking change.
Now that enums are also going to be able to have private fields, I think this guideline should also drop the "struct" part. Maybe the guideline could be replaced with something like this:
AGGREGATE-PRIVATE-FIELD
If an aggregate field is public, then making it private or changing its type or name is a semver breaking change. If an aggregate only contains public fields, then adding any field to it, including private fields, is a semver breaking change. Aggregates can be future-proofed code against these semver breaking changes by adding a private field or by using the
#[non_exhaustive]attribute. Note that private fields are not allowed in tuples or arrays, that is, adding a field to a public tuple or changing the length of a public array is always a semver breaking change.Other changes to aggregates that only contain public fields, like, for example, changing the field order, are also semver breaking changes for some representations like
repr(C), which allow users to use the aggregate in, e.g., FFI, where other aspects of the type like its call ABI, field order, etc. are often relied on.
There was a bit of discussion about this here: https://github.com/rust-lang/rust/issues/44109#issuecomment-534601202
This seems like a reasonable amendment to me. We should probably include some description of what an aggregate is so users browsing the guidelines know we're talking about enums or structs.
We’re still getting an idea of what kinds of amendments need to run through an FCP or not. On a second reading, this update seems reasonable and uncontentious enough to me to not need one.