Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add "unit struct to normal struct" case to semver.md #10871

Closed
wants to merge 4 commits into from
Closed
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 37 additions & 0 deletions src/doc/src/reference/semver.md
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,7 @@ considered incompatible.
* Structs
* [Major: adding a private struct field when all current fields are public](#struct-add-private-field-when-public)
* [Major: adding a public field when no private field exists](#struct-add-public-field-when-no-private)
* [Major: going from a unit struct to a normal struct, even if it has no fields](#struct-unit-to-normal)
* [Minor: adding or removing private fields when at least one already exists](#struct-private-fields-with-private)
* [Minor: going from a tuple struct with all private fields (with at least one field) to a normal struct, or vice versa](#struct-tuple-normal-with-private)
* Enums
Expand Down Expand Up @@ -273,6 +274,42 @@ Mitigation strategies:
a struct to prevent users from using struct literal syntax, and instead
provide a constructor method and/or [Default] implementation.

<a id="#struct-unit-to-normal"></a>
### Major: going from a unit struct to a normal struct, even if it has no fields

A unit struct can be constructed using both `Unit` and `Unit {}`
[struct literal] syntax. However, the curly braces are mandatory for
normal structs, even ones with no fields.

If the unit struct was not [`#[non_exhaustive]`][non_exhaustive],
changing it to a normal struct will break any code that constructs
it using a [struct literal] without the curly braces.

```rust,ignore
// MAJOR CHANGE

///////////////////////////////////////////////////////////
// Before
pub struct Foo;

///////////////////////////////////////////////////////////
// After
pub struct Foo {}

///////////////////////////////////////////////////////////
// Example usage that will break.
use updated_crate::Foo;

fn main() {
let x = Foo; // Error: expected value, found struct `Foo`
// ^^^ help: use struct literal syntax instead: `Foo {}`
}
```

Mitigation strategies:
* Mark the unit struct [`#[non_exhaustive]`][non_exhaustive] when first
adding it, to make it impossible to construct outside of its own crate.

<a id="struct-private-fields-with-private"></a>
### Minor: adding or removing private fields when at least one already exists

Expand Down