RFC: Policy on semver and API evolution

[aturon]

This RFC proposes a comprehensive set of guidelines for which changes to
stable APIs are considered breaking from a semver perspective, and which are
not. These guidelines are intended for both the standard library and for the
crates.io ecosystem.

This does not mean that the standard library should be completely free to make
non-semver-breaking changes; there are sometimes still risks of ecosystem pain
that need to be taken into account. Rather, this RFC makes explicit an initial
set of changes that absolutely cannot be made without a semver bump.

Along the way, it also discusses some interactions with potential language
features that can help mitigate pain for non-breaking changes.

The RFC covers only API issues; other issues related to language features,
lints, type inference, command line arguments, Cargo, and so on are considered
out of scope.

Rendered

[aturon]

@bstrie, I know you were interested in this.
@pnkfelix I could use your careful eyes on this one!
cc @alexcrichton @sfackler @brson @huonw @wycats @nikomatsakis

[aturon]

cc @reem @carllerche -- I think both of you have also expressed some opinions on this topic as well. (This is an important piece of policy, so I want to ensure good visibility).

[sfackler]

A slightly weaker way of phrasing this would be "given knowledge of any change, it should be possible to write a version of your code that works both before and after that change". It seems to me like that phrasing is significantly more important to guarantee than the version written, since it means libraries won't be "forced" to abandon old versions of Rust to support new versions.

[aturon]

Yes, that's also an important constraint, and I'll try to rewrite to clarify.

That said, what's gradually becoming clear to me with this RFC is that we may be able to make a strictly stronger guarantee: that all minor but breaking changes can be worked around automatically with an elaboration process. (I think with a couple of very minor language features, we can get there.) Having a strong guarantee that you don't have to go make changes to your dependencies when you upgrade Rust -- while allowing the standard library to grow -- seems like a great place to be.

[sfackler]

We could also update the compiler to allow both Foo(..) and Foo {..} if all fields are private. If the type's "totally opaque", it kind of makes sense that the kind of struct would be hidden as well.

[reem]

I agree with @sfackler, I've viewed this as a wart and we could just fix it.

[nikomatsakis]

Strictly speaking, Foo(..) looks up a match in the value namespace, I believe, though perhaps that is not necessary given our current semantics (basically, for anything where the Foo(..) pattern would be legal, it could also check the type namespace now).

[huonw]

This may implicitly cause a crate to require nightly if a dep does.

[lilyball]

Perhaps this should just be covered under something like

Major change: any change that requires a nightly when the crate did not previously require a nightly

This includes introducing #[feature] for the first time, or adding/upgrading a dependency which requires a nightly.

[cmr]

Additionally, adding/removing dependencies can modify the cargo feature set (not #[feature]) exposed to upstream, which can implicitly cause breaking changes if you accidentally used a #[cfg]d off function.

[aturon]

@huonw @kballard Thanks, I will take @kballard's suggestion for the wording here.

@cmr That is an interesting scenario, but I don't think it should be considered a major change: if other crates were relying on the feature without specifying it, they're basically breaking the model (and can be easily fixed by opting into the feature themselves).

[huonw]

(Missing space after !.)

[sfackler]

This is not actually the case right now since #213 isn't fully implemented:

enum Foo<S = i32> {
    Bar,
    Baz(S)
}

fn f<S>(_: Foo<S>) {}

fn main() {
    f(Foo::Bar);
}

~ ❯ rustc test.rs
test.rs:9:5: 9:6 error: unable to infer enough type information about `_`; type annotations required [E0282]
test.rs:9     f(Foo::Bar);
              ^
error: aborting due to previous error

[petrochenkov]

Yep, until default type parameters drive type inference, generalization can cause surprisingly large breakage. For example heterogeneous comparisons for Option can't be implemented now because they would require type annotations on None in every comparison and that's a lot of annotations.
Default parameters is an important backward compatibility tool, I hope they'll be finished sooner.

[huonw]

Should we have a lint?

[reem]

Does this mean we are in fact freezing io::ErrorKind?

[sfackler]

ErrorKind has an unstable variant that prevents stable code from exhaustively matching on it: https://github.com/rust-lang/rust/blob/master/src/libstd/io/error.rs#L118-L123

[sfackler]

A somewhat related concept would be changing the major version of a dependency. It seems like that could be either a minor or major change depending on if the crate is visible in your crate's public API or not.

[lilyball]

Does Cargo allow multiple versions of the same crate to exist in a single dependency tree, or does it restrict each crate to only resolving to a single version? My assumption has been the latter (although some language package managers do the former, such as npm). If it's the latter, then any major version upgrade for a dependency could be a breaking change if the dependency already exists anywhere else in the upstream crate's dependency tree.

By the same logic, the addition of any dependency (using anything other than * as the version requirement) could be a breaking change.

[alexcrichton]

Cargo allows multiple versions of a project, but each version must be semver incompatible with all other activated versions. For example 1.0.0 and 2.0.0 are allowed, but 1.0.0 and 1.1.0 is not.

[lilyball]

Interesting. So it sounds like it's still possible for the addition/upgrade of a dependency to be an incompatible change if the version requirement depends on anything other than the major version number, e.g. foo = ">1.1.0" would be a breaking change if a different project in the dependency tree had foo = "=1.0.5".

[aturon]

Hm, this is a very interesting and somewhat thorny point.

My inclination would be to say that it's a minor change to increase the minor version number as long as the spec is of the form >X.Y.Z, and basically assume that a fully locked-down spec like =X.Y.Z is a corner case that opts out of the API stability guarantees.

Thoughts?

[huonw]

This would have to be Trait2::foo(t) or <T as Trait2>::foo(t), wouldn't it? (Otherwise it's trying to go via the trait object type?)

[huonw]

adding/removing

[huonw]

Worth discussing #[deny(...)] causing compilation errors in more detail? (cc #1029 )

[aturon]

I'm not sure whether this RFC is the right place to tackle that infrastructure, but I'll at least put in a reference.

[huonw]

Similarly, the beta releases are designed for exactly this purpose.

[lilyball]

FWIW, there is a way around this. The obvious answer is to implement Default for the struct, allowing literals of the form Foo { a: 1, b: 2, ..Default::default() }.

This solution won't work for struct literals found in const or statics (although a const containing a default value for the struct would). But there's plenty of other changes you can make to structs that would break struct literals found in const or static but not break struct literals found elsewhere (for example, adding a public field that has no public value that can be used in a const or static). Given that, requiring that any change not break the ability to use struct literals in const / static might be considered overly restrictive (especially as most types will never find themselves used in that fashion). And if that restriction is not enforced, then it seems plausible to treat a pre-existing implementation of Default as allowing for changes that would otherwise break struct literals.

[pnkfelix]

@kballard I take it you are assuming that RFC 736 would be reverted in order to enable this pattern?

That is, this pattern used to work, but it does not any longer, because the privacy breakage allowed inadvertent exposure of the internal representation and subsequent breakage of global invariants.

[lilyball]

@pnkfelix Oh. I actually had never even seen RFC 736. I missed that change completely.

Incidentally, is there some reason that this was disallowed completely, instead of only for types that aren't Copy? Using FRU for a Copy type is equivalent to copying it and mutating the public fields. I'll file an RFC on it. (Update: Filed as #1117)

[pnkfelix]

@kballard (i don't think there was any reason beyond adopting the "simplest" change that could possibly work, where "simplest" is measured according to some hand-wavy ordering w.r.t. the description of the language itself)

[Gankro]

Exceedingly little code can even distinguish between an abort and a panic, so I wouldn't expect this to be a serious problem in practice. The only thing I can see being trouble is unsafe code, which can legitimately rely on the fact that something aborted to avoid setting up guards against unwinding. In such a case this could lead to UB! However if we had no_unwind assertions or something unsafe code could at least guard against such a change. Although adding no_unwind assertions would make this change even-more-breaking!

panic -> Err seems like a tricky semantic change that can cause weird error-handling bugs. For one, if API A declares that it panics on input X, and API B uses API A but also transitively reports the panic in one of its APIs for input Y, its documentation will at best be incorrect after an upgrade: it no longer panics on Y.

Otherwise you may just get bad error handling results from things like "what I thought was an effectively exhaustive match no longer is (new Error kinds are possible -- basically a soft version of adding a variant to an enum)" or "The system reports frobs are out of sync on error X since this is the only possibility in 1.0, but since 1.1 it can now also mean frams are misaligned (old Error kinds are now more overloaded)". This seems like a major breaking change from a semantic perspective.

[oli-obk]

This could rather be solved by importing neither, but noting the name. When the code uses an item with that name, an error "item not imported due to conflicting glob imports" could list all possibilities and suggest adding an explicit use

[aturon]

Good point! I'll add that proposal as well.

[P1start]

s/so is/so are/ – ‘the full contents’ is plural.

[P1start]

I believe that considering this a minor change this goes against the overview’s ‘principles of the policy’:

That means that any breakage in a minor release must be very "shallow": it must always be possible to locally fix the problem through some kind of disambiguation that could have been done in advance (by using more explicit forms) or other annotation (like disabling a lint). It means that minor changes can never leave you in a state that requires breaking changes to your own code.

As far as I know, there’s not always a way of ‘fix[ing] the problem through some kind of disambiguation that could have been done in advance’ for this kind of change. To explain with an example, if the breaking change example mentioned in the RFC (adding an extra type parameter to fn foo<T>) occurred in the standard library between, say, Rust 1.3 and 1.4, and my library (which depended on std) had code that called foo with an explicit type parameter (like foo::<u8>()), I’d have no way of fixing my code in a way that continues to support Rust 1.3 but also supports the newest version of Rust. In other words, I’d have to make a choice between supporting the older versions of Rust that I supported and supporting the newer versions (which have an extra type parameter on foo).

The section mentioned above does say ‘in principle’, but it also says that the RFC should suggest ‘additional tooling or language support’, neither of which seems to be outlined in the RFC to address this particular problem.

[oli-obk]

In almost all situations I can think of, you can probably use type ascription either in the parameters or in the return value. Any situations where this isn't enough probably have global state and are abusing generic code.

[P1start]

I disagree. To give a more concrete example, imagine that std provided a function for calculating the hash of a value:

pub fn hash<T>(value: &T) -> u64 where T: Hash {
    let mut h = SomeHasher::new();
    value.hash(&mut h);
    h.finish()
}

Let’s pretend that I have a library (which depends on std) that has code that looks like hash::<u8>(1). Now, in Rust 1.4, the function above has a new type parameter added to make it generic over the hasher used:

pub fn hash<T, H>(value: &T) -> u64 where H: Default + Hasher, T: Hash {
    let mut h: H = Default::default();
    value.hash(&mut h);
    h.finish()
}

According to the RFC, this would be a minor change. However, there is no way for me to update my code in a way that supports both 1.3 and 1.4—in 1.4, I have to specify the second type parameter, but in 1.3, I can’t.

I suppose this doesn’t apply to most functions (only those where not all type parameters can be inferred), but I think that the RFC should at least specify that this is only a minor change if there is a way of inferring the type of all type parameters (new and old).

[lilyball]

@P1start Your example there can infer its type parameter, and your example invocation hash::<u8>(1) won't work to begin with.

[huonw]

I wonder if we could allow hinting only a prefix of the generic type parameters, this would make situations like this where the new type parameter is inferrable always just work. I have at least one API where this would be useful myself (functions are usually called like either foo::<X, _>(), with the _ essentially never needing to be specified).

[P1start]

@kballard The second type parameter doesn’t seem to be inferred when using std’s existing Hash[er] traits. And the invocation should have been hash::<u8>(&1) (but that’s just a mistake and is beside the point).

[lilyball]

@P1start I was referring to that first code snippet. With the second code snippet, the addition of a non-inferrable type parameter would of course be a breaking change, and I would expect anyone making such a change to provide a default value for the type parameter (or if they really don't want to, then to consider it a major version bump).

[nikomatsakis]

@aturon I'll go over in detail, but one thought I had is that it might be useful to elaborate a kind of "best practices for forwards compatibility". That's probably not part of this RFC, but it might help illuminate nonetheless.

[nagisa]

Nit: redundant paragraph. Language, lints, type inference, CLI are not part of standard library (first paragraph), nor they are a part of crates.io ecosystem.

[pnkfelix]

In the past, for better or worse, sometimes changes to things like command line arguments to rustc were for various reasons classified as "library issues" (as opposed to language issues).

(Also, the list here covers things that might be part of semantic versioning for the Rust language itself -- I think the rules there still remain unwritten. So given that the title of this RFC is "policy on semver ...", it is natural for a reader to perhaps wonder if these issues are in fact addressed...)

While the first paragraph does indeed restrict the domain to "standard library" and "crates.io ecosystem", I think this paragraph can stay -- perhaps just modify it to make it clear that this paragraph is in fact a consequence a fact that all these things are not part of the standard library nor crates.io ecosystem.

[SimonSapin]

There are behavior changes like #23951 Changing the meaning of the count to splitn that are not breaking per the definition in this RFC (they do not cause downstream code to fail to compile), but still should be considered major as they break basic expectations that downstream code could reasonably make.

Unfortunately I don’t see a clear criteria to distinguish those from behavior changes that are more reasonable or expected like changing results of char::is_alphabetic when updating to a new Unicode version.

[aturon]

@SimonSapin Did you see the earlier section on behavioral changes? The rough guideline would be that changes that break the explicit, documented behavioral contract of a function are considered breaking.

[BurntSushi]

I very much love this RFC. Nice work @aturon!

[Havvy]

This link is dead.

[theemathas]

What happens if someone finds another way to cause unsafty using safe code and the standard library? We already had thread::scoped and Vec::drain.

[tbu-]

This is not true, consider the change to Iterator::sum, which (even though it specifies a default for the type parameter) can't be inferred everywhere.

[huonw]

I suspect that is the same problem discussed below: https://github.com/rust-lang/rfcs/pull/1105/files#r29635875

[apasel422]

Should this mention changing an object-safe trait in such a way that it is no longer object-safe?

[theemathas]

What about changing an unsafe function to a safe function?

[ruuda]

There are two angles to versioning, and I think the difference is important:

1. Given that the next release will not be major, can we include this change?
2. Given that we are going to include this change, what should the version number for the next release be?

If I understand the release train model correctly, the version number is determined before changes that will be included in that version are made, so Rust is in scenario 1. If major bumps are going to be uncommon, then it makes sense to downplay some technically breaking changes as minor.

For Crates.io, I expect the vast majority of crates to be in scenario 2. I think the pragmatic approach is a good one; adding a public item without changing anything else certainly feels like a new feature, not like a backwards incompatible change. However, to play the devil’s advocate: there appears to be a hidden assumption that a major version bump is bad and should be avoided. I agree that backwards incompatible changes should be avoided if possible, but this RFC is about naming only. If a change is technically breaking and will be included in the next release, the only question is what the version number should be. Why downplay technically breaking changes as minor? To quote the sidebar rules:

5 . Chill out! A programming language version number is a silly thing to get upset over.

[Stebalien]

It would be kind of nice to include a machine readable API change file in minor updates. Cargo could use this to at least prevent silent breakage. Theoretically, cargo could also use this to automatically disambiguate but I don't know if we really want to rewrite user code and take responsibility for any bugs that might result (we'd have to be REALLY careful and would probably want to prompt the user for every change).

[aturon]

Sorry for the delayed responses, I'm digging out from a bunch of stuff near the 1.0 release.

One general question that @wycats has raised offline with me is: do we need to require a full implementation of elaboration before we can fully embrace the policy here? Certainly this RFC is strengthened by various implementation work (glob import refinements probably being the most important), but my feeling is that we can adopt this basic framework even without working elaboration, but be especially judicious with checking changes against Crater for breakage. But I'd be curious to hear others' thoughts on this.

@pnkfelix

Regarding macros: this is definitely something we should think about, but I'm much less confident about what to say there at the moment, and we are also relatively conservative about the macros we export from std. I'm inclined to punt on these questions for now.

@bstrie

Would it be worthwhile to go through and study the regression reports from the past four weeks and characterize each occurrence of breakage according to the categories presented here?

Hm, I don't think so -- most of the breakage in the runup to 1.0 would fall into the "requires major version bump", I believe.

I don't think we want to commit to running Crater with every minor change. Is the current cadence of once-a-week reports too slow?

That's a good point. It may be worth further specifying which minor changes need a look on Crater. In particular, simply adding a public item shouldn't require it, even though it could break glob imports -- partly because we should make globs more robust, but partly because we wouldn't be deterred from making a change for that reason (I don't think). Whereas adding a defaulted method to a trait should definitely be tested on Crater for conflicts.

Regarding the existing regression reports: I was imagining this happening during prototyping/early implementation, rather than after landing in nightly. But maybe it's enough to land PRs directly to nightly as assess the breakage there, and then consider yanking breaking changes well before stabilization.

One other thing to keep in mind: a stable build still ships with all of the nightly APIs; it just lints on them. That means that basically all breaking changes would be immediately apparent on stable builds too; there's not a lot of margin for error here.

Is there any possibility that the changes to name resolution from such an RFC would be a breaking change? Are we allowing ourselves that possibility because "we intended it to be this way"?

Yes, it's possible, though @nrc took some pains to future-proof resolution for exactly this reason. And yes, I think these can largely be considered "bug fixes". But we should try to do them soon.

@bluss

What about changing a crate from depending on Rust 1.0 to Rust 1.1 (and so on)? This is a non-breaking change I assume.

Yes, I would agree -- in particular, if we assume that upgrading from 1.0 to 1.1 is itself not breaking (in a major way), then requiring that upgrade shouldn't count either.

default type parameters for functions & methods aren't fully implemented, they don't seem to work really. So this can be addressed partially by just finishing that.

Yep, we definitely need some implementation work in this area to make this RFC fully fly.

@Stebalien

I'd explicitly exclude the following design pattern from this restriction ...

Seems fair, but even better would be to land the equivalent first-class language features. :)

[comex]

An idea:

The original version of #1122 proposed having a Rust version attribute in each crate's Cargo.toml. That has since been removed in favor of a more minimal PR, but suppose it ends up happening. What if rustc automatically versioned the standard library based on that number, preventing minor changes from actually breaking anything (in a better way than elaborated source, see below)? All #![stable] declarations in the standard library already have an associated Rust version number; this wouldn't be quite sufficient to take care of all ambiguities, but it'd be close. Specifically:

• When resolving dispatch ambiguity for a method call, if some of the possible methods are stable in a version later than the caller crate's (or unstable), and others aren't, discard the former.
• Ditto for glob imports: while having explicit items shadow glob-imported ones avoids problems in most use cases, there is still the case of conflict between multiple glob imports, which can be resolved in the same way.
• Optionally: rather than using version comparison to resolve conflict, simply forbid newer items from being used by older crates altogether, in the same way as unstable items. This makes it harder to accidentally break compatibility with older Rust versions, and provides a carrot for libraries to upgrade and properly resolve the breaks. Also might make the below a bit easier to implement.
• New template parameters: add a separate stability attribute for template parameters and allow older crates to omit them without .... Or just allow that in all cases, might make things simpler.
• Introducing generics: this is the ugliest one, but compatibility can be solved by having a mechanism for the standard library to specify the old version of the signature, then having type inference use that version for older code, while still checking afterward that the resolved parameters match the new signature.

The last two sound a bit ugly, but I think it should be fairly rare for such changes to existing items to be made in the first place. Implementation of the type inference change sounds like it could be a challenge.

Edit: (...Perhaps a better solution for those would be to just allow entirely separate declarations that apply to versions < and >= X, rather than any messing with type inference or template parameters.)

So why go to this effort, if all minor changes are designed to break little code in the first place? A few reasons:

• A rustfix that was fully automated would have to do the same work (including the ugly bits with type inference), unless it resorted to full elaboration (i.e. sticking types in everywhere whether needed or not), which would work as a quick fix but be pretty useless as an upgrade path. Intermediate solutions may be possible, though.
• Elaborated source would require either having an already built copy of your library dependency or downloading a specific old version of rustc. This means that while cargo could do the conversion automatically, it would be a major usability hassle. In contrast, by maintaining the required information in the current source as above, users would not suffer if libraries just sat on older versions forever - which sounds gross, but is going to happen one way or another, because code often gets abandoned by its authors.
• With such a robust upgrade path, it would be possible to be slightly more liberal than this RFC proposes in making small breaking changes. Of course, there are many huge downsides to breaking things, period - examples on the Internet, upgrade hassle, etc. - and I don't have any specific suggestion about what sorts of changes could be allowed - but especially combined with Crater, there is at least a bit more wiggle room.
• And if it turns out to be desirable to release a Rust 2.0 in 1 year or 10, the same mechanisms could be used to avoid a Python 3-like flag day. (Language changes would probably make this trickier than usual, but that's a matter for the other RFC - it's my opinion that enough languages have successfully pulled this off that Rust should be able to, too.)

Edit: The same mechanisms could be adapted for use by independent crates. They ought to have equivalent ways to mark things stable or not anyway... nothing special about the standard library in its desire to introduce experimental features without committing to them.

[alexcrichton]

This RFC is now entering the week-long final-comment period.

[huonw]

I'm in favour, but I think that we will definitely want to be "quick" to make amendments (to the process, even if we don't literally change the text here) in future as we gain more experience, and as the ecosystem/community changes.

(I'm also a little nervous about #1105 (comment) .)

[alexcrichton]

The consensus of the library subteam is to merge this RFC. We may tweak the specifics here and there over time, but there is broad consensus among the core ideas behind this RFC and minor updates are always fine to make later!

[aturon]

It occurred to me today that this RFC did not take into account the impact of "OIBIT" traits (which have a .. impl). In particular, these traits can introduce downstream sensitivity to every aspect of a data type's representation, even if that representation is private.

Effectively, OIBITs make it possible for downstream crates to make promises on behalf of upstream crates that can easily be broken.

I don't think this should change anything about the policy itself, but it'd be worth amending the RFC to discuss it.

RFC issue