[book] add chapter on breaking changes #7831

guswynn · 2020-01-25T23:20:54Z

As far as I can tell, rust-lang/rfcs#1105 are the de-facto guidelines that crate maintainers should use to guide their use of semver for this crates.

I have found it confusing in the past that these guidelines don't exist in any documentation outside that RFC, and discussion in rust-lang/rust#68004 led be to believe that it's worth it to add this to some official documentation.

See rust-lang/reference#738 for more details

@ehuss I only added the chapter on breaking changes, not the

one on version unification and versioning guidelines,
I can add that as well, but I would need guidance on that. I think once that exists, that this should be a subchapter.
I also think I have edited this (originally derived from the rfc) to make sense as a part of the cargo guide, but of course that's up to review, and I'm willing to change it!

rust-highfive · 2020-01-25T23:21:04Z

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @alexcrichton (or someone else) soon.

If any changes to this PR are deemed necessary, please add them as extra commits. This ensures that the reviewer can see what has changed since they last reviewed the code. Due to the way GitHub handles out-of-date commits, this should also make it reasonably obvious what issues have or haven't been addressed. Large or tricky changes may require several passes of review and changes.

Please see the contribution instructions for more information.

ehuss

Thanks for getting this started!

I think there's some stuff missing here. It seems like there are a lot of changes to item signatures not covered. Another is attributes. I'd also like to highlight some of the "grey area" things where not everyone agrees if it is a breaking change or not. One in particular is rust version support, and also platform requirements (like a new release requires a new version of macOS, or a newer system library, or anything really). I'm not sure if we need to exhaustively hit everything in this PR, but any help working through them would be appreciated.

ehuss · 2020-02-04T16:34:31Z

src/doc/src/breaking.md

@@ -0,0 +1 @@
+# Breaking Changes


This looks like a stray file?

ehuss · 2020-02-04T16:36:03Z

src/doc/src/reference/breaking.md

+2. **Minor**: incremented for backwards-compatible feature additions.
+3. **Patch**: incremented for backwards-compatible bug fixes.
+
+> **Note** As well as the rule that versions **<1.0.0** can change anything.


This isn't quite correct. Cargo treats 0.y.z where changes in z are compatible.

ehuss · 2020-02-04T16:36:34Z

src/doc/src/reference/breaking.md

+> **Note** As well as the rule that versions **<1.0.0** can change anything.
+
+Typically, a **breaking change** is a change that, *strictly speaking*, can cause downstream
+code to fail to compile


Suggested change

code to fail to compile

code to fail to compile.

ehuss · 2020-02-04T16:39:15Z

src/doc/src/SUMMARY.md

@@ -21,6 +21,7 @@
 * [Cargo Reference](reference/index.md)
    * [Specifying Dependencies](reference/specifying-dependencies.md)
        * [Overriding Dependencies](reference/overriding-dependencies.md)
+    * [Breaking Changes](reference/breaking.md)


Mind moving this down a bit? The Manifest Format is one of the most important chapters, and I'd like it to be near the top. Maybe down near the "Publishing" chapter, since this is kinda related to publishing.

I'm also wondering if maybe it should be placed in a sub-folder, and breaking it up a little? The chapter is a bit difficult to navigate (or see an overview).

I'm also thinking maybe naming it "Version Compatibility"? Or "SemVer Compatibility"?

ehuss · 2020-02-04T16:41:57Z

src/doc/src/reference/breaking.md

+(The use of `?Sized` is essential; otherwise you couldn't recover the original
+signature).
+
+[rfc]: https://github.com/rust-lang/rfcs/pull/1105


Suggested change

[rfc]: https://github.com/rust-lang/rfcs/pull/1105

[rfc]: https://github.com/rust-lang/rfcs/blob/master/text/1105-api-evolution.md

ehuss · 2020-02-04T17:45:12Z

src/doc/src/reference/breaking.md

+impl, which has the wrong type.
+
+Once more, this is considered a minor change, since UFCS can disambiguate (see
+"Adding a defaulted item" above).


Link to section.

And maybe add <a> tags to create shorter and more stable url fragments?

ehuss · 2020-02-04T17:45:38Z

src/doc/src/reference/breaking.md

+It's worth noting, however, that if the signatures *did* happen to match then
+the change would no longer cause a compilation error, but might silently change
+runtime behavior. The case where the same method for the same type has
+meaningfully different behavior is considered unlikely enough that the RFC is


ehuss · 2020-02-05T02:48:05Z

src/doc/src/reference/breaking.md

+
+**Breaking changes are assumed to be major changes unless otherwise stated**.
+The RFC covers many, but not all breaking changes that are major; it covers
+*all* breaking changes that are considered minor.


This is a bit of a strong statement, I'm not sure if it is accurate since I don't consider this list to be exhaustive.

ehuss · 2020-02-05T02:50:23Z

src/doc/src/reference/breaking.md

+[ufcs]: https://doc.rust-lang.org/1.7.0/book/ufcs.html
+[semver]: https://semver.org/
+[features]: http://doc.crates.io/manifest.html#the-[features]-section
+[opt-in_features]: http://doc.crates.io/manifest.html#the-[features]-section


Suggested change

[opt-in_features]: http://doc.crates.io/manifest.html#the-[features]-section

ehuss · 2020-02-05T02:51:12Z

src/doc/src/reference/breaking.md

+[semver]: https://semver.org/
+[features]: http://doc.crates.io/manifest.html#the-[features]-section
+[opt-in_features]: http://doc.crates.io/manifest.html#the-[features]-section
+[postponed_RFC]: https://github.com/rust-lang/rfcs/pull/757


Suggested change

[postponed_RFC]: https://github.com/rust-lang/rfcs/pull/757

guswynn · 2020-02-05T03:51:03Z

@ehuss I'm willing to help out on the missing pieces! I've noticed that other books in the rust ecosystem has TODO's, will that suffice here, so that extensions can be added in later pr's?

ehuss · 2020-02-05T17:18:17Z

I think writing them down in a tracking issue on this repo would be fine.

ehuss · 2020-05-15T14:29:16Z

@guswynn Was wondering if you're still interested in working on this. I might have a little extra time, so I was thinking of moving it forward.

guswynn · 2020-05-15T14:43:30Z

I may be able to find time to work on in this weekend, can I put it on hold for 2 more days, after that you can take it?

…

On Fri, May 15, 2020, 7:29 AM Eric Huss ***@***.***> wrote: @guswynn <https://github.com/guswynn> Was wondering if you're still interested in working on this. I might have a little extra time, so I was thinking of moving it forward. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#7831 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABJHND2FAG3TQBFIUWRC5ALRRVGUZANCNFSM4KLTTIHA> .

ehuss · 2020-05-15T14:47:21Z

Sounds good!

ehuss · 2020-09-03T19:36:54Z

I'm going to close, as this is now incorporated in the book: https://doc.rust-lang.org/nightly/cargo/reference/semver.html

guswynn · 2020-09-03T23:47:25Z

@ehuss I'm so sorry, I ended up having a bout of time where I couldn't spend any time on this!

rust-highfive assigned alexcrichton Jan 25, 2020

rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Jan 25, 2020

guswynn force-pushed the breaking branch from ed839ea to b81a061 Compare January 25, 2020 23:23

add chapter on breaking changes

54efdb2

guswynn force-pushed the breaking branch from b81a061 to 54efdb2 Compare January 25, 2020 23:23

ehuss assigned ehuss and unassigned alexcrichton Jan 25, 2020

ehuss reviewed Feb 5, 2020

View reviewed changes

ehuss added S-waiting-on-author Status: The marked PR is awaiting some action (such as code changes) from the PR author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Feb 18, 2020

ehuss closed this Sep 3, 2020

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[book] add chapter on breaking changes #7831

[book] add chapter on breaking changes #7831

guswynn commented Jan 25, 2020

rust-highfive commented Jan 25, 2020

ehuss left a comment

ehuss Feb 4, 2020

ehuss Feb 4, 2020

ehuss Feb 4, 2020

ehuss Feb 4, 2020

ehuss Feb 4, 2020

ehuss Feb 4, 2020

ehuss Feb 4, 2020

ehuss Feb 5, 2020

ehuss Feb 5, 2020

ehuss Feb 5, 2020

guswynn commented Feb 5, 2020

ehuss commented Feb 5, 2020

ehuss commented May 15, 2020

guswynn commented May 15, 2020 via email

ehuss commented May 15, 2020

ehuss commented Sep 3, 2020

guswynn commented Sep 3, 2020

	[rfc]: https://github.com/rust-lang/rfcs/pull/1105
	[rfc]: https://github.com/rust-lang/rfcs/blob/master/text/1105-api-evolution.md

[book] add chapter on breaking changes #7831

[book] add chapter on breaking changes #7831

Conversation

guswynn commented Jan 25, 2020

rust-highfive commented Jan 25, 2020

ehuss left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

guswynn commented Feb 5, 2020

ehuss commented Feb 5, 2020

ehuss commented May 15, 2020

guswynn commented May 15, 2020 via email

ehuss commented May 15, 2020

ehuss commented Sep 3, 2020

guswynn commented Sep 3, 2020