Can we make 1.0 releases of packages non-breaking?

[collinjackson]

Flutter packages have a special update to 1.0 when they reach API stability. This doesn't actually need to be a breaking change, but the version solver treats it as one, leading to conflicts at the worst possible time - when a package is just achieving popularity. As a result, the incentives for developers to stabilize their APIs is low.

If we could teach the constraint solver to be aware that 1.0 promotions aren't breaking, we wouldn't need to inflict pain on the ecosystem just as a package is reaching widespread usage, and developers might get to 1.0 faster.

Straw proposal:

• The constraint solver could treat version "1.x.0, 0.42.x" as satisfying a request for ^0.42.x+y or ^1.x.y.
• It could be an error for the minor versions (x) to not match. Or alternatively the minor and patch versions of 0.42 could be implied and omitted.
• Minor updates would keep the pre-1.0 major version locked at the major version that was initially promoted. So in this case pub would reject any pre-1.0 version other than (0.42) once the promotion occurred. Version 1.1.0 (0.42) would satisfy a request for ^0.42.0 or ^0.42.100 or ^1.0.0 or ^1.1.0.
• Breaking changes would force a major update to 2.0.0, at which point the pre-1.0 version number would no longer be relevant.

(Problem statement and proposal are based on discussions with @amirh.)

Context:

https://semver.org/
https://dart.dev/tools/pub/versioning

[jonasfj]

The straw proposal here is to essentially allow a package version to satisfy multiple version constraints.

This could also be expressed by simply listing multiple additional compatible versions in the pubspec.yaml. Interesting, but perhaps a bit scary too.

---

But traditionally this solved differently. Consumers of the package should not write ^1.0.0 instead they should be directed to write >=0.42.0 <2.0.0 as their version constraint.

For your case I assume the problem is that other packages depend on either ^1.0.0 or ^0.42.0, thus, these other packages are incompatible. Writing a script to find these packages no pub.dev would be easy. But it's not clear that devs would be quick to accept PRs.

For downstream app developers who experience package incompatibilities because of this dependency_overrides is the intended escape hatch -- but I would discourage us from establishing a culture relying on this -- it may cause other bugs if packages are indeed incompatible.

---

Another option is stop using version numbers to signal stability. Switch to 1.0.0 as soon as other packages starts depending on your package. This may cause you to end up with version 42.0.0 instead of 0.42.0, but such.is the nature of semver.

Trying to make 1.0.0 special is perhaps a problem.

[collinjackson]

This could also be expressed by simply listing multiple additional compatible versions in the pubspec.yaml. Interesting, but perhaps a bit scary too.

I agree that this could generalize further, but that doing so could lead to confusing situations. And once pub starts allowing it, it could be hard to roll back.

Consumers of the package should not write ^1.0.0 instead they should be directed to write >=0.42.0 <2.0.0 as their version constraint.

The consumer has no way of knowing for sure that the developer is going to make the next version a bump to 1.0 until it's done. If the consumers of the package depend on >=0.42.0 <2.0.0 and the package author decides to release a breaking change as 0.43.0 wouldn't be treated as a breaking change, leading to compilation errors. Once the bump to 1.0 has already happened, there's certainty... it's in the past and the consumers can all migrate to >= 0.42.0 <2.0.0 but there's a period of time where packages are incompatible until everyone updates.

For your case I assume the problem is that other packages depend on either ^1.0.0 or ^0.42.0, thus, these other packages are incompatible. Writing a script to find these packages no pub.dev would be easy. But it's not clear that devs would be quick to accept PRs.

Even if the developer goes through the effort of doing this, there's still going to be a period of time where the package is version locked -- there's no first mover advantage for dependent packages to accept the new version because doing so would make them incompatible with the herd. It makes sense to do this if there's some new functionality enabled by the breakage.

Switch to 1.0.0 as soon as other packages starts depending on your package.

Switching to 1.0.0 signals an API break when there is none, which is the concern that started this issue. It seems like this is equivalent to pub just prohibiting publishing of pre-1.0 plugins. What is the point of publishing a pre-1.0 package on pub if you don't want other packages to use it? Why should the inclusion of dependent package on pub force the developer to change versions?

Another option is stop using version numbers to signal stability. Switch to 1.0.0 as soon as other packages starts depending on your package. This may cause you to end up with version 42.0.0 instead of 0.42.0, but such.is the nature of semver.

If we're going to do this we could just prohibit pre-1.0 plugins. But I feel like "I haven't made a breaking API change in a long time and don't plan to" is a meaningful point in the life cycle of a plugin that could be used to surface higher-quality plugins.

Trying to make 1.0.0 special is perhaps a problem.

Why is it a problem to make 1.0 special? We already treat 0.x plugins as special.

[isoos]

Why is it a problem to make 1.0 special? We already treat 0.x plugins as special.

I'm not sure if I follow this: what treats 0.x plugins as special?

Switching to 1.0.0 signals an API break when there is none,

There may be, we can't know for sure just looking at the version number. I think it is better if a developer of a package makes a conscious and explicit decision on what is supported and what should work with the current release. Anything else seems to be a guesswork, which may be working in 95% of the cases, but then it would give surprising side-effects and unintended consequences in other cases.

I think the dependencies_override is a good way for a consumer of the libraries to override a package's dependency if it is lagging behind.

[collinjackson]

Why is it a problem to make 1.0 special? We already treat 0.x plugins as special.

I'm not sure if I follow this: what treats 0.x plugins as special?

See https://dart.dev/tools/pub/versioning#semantic-versions

"Although semantic versioning doesn’t promise any compatibility between versions prior to 1.0.0, the Dart community convention is to treat those versions semantically as well. The interpretation of each number is just shifted down one slot: going from 0.1.2 to 0.2.0 indicates a breaking change, going to 0.1.3 indicates a new feature, and going to 0.1.2+1 indicates a change that doesn’t affect the public API."

Switching to 1.0.0 signals an API break when there is none,

There may be, we can't know for sure just looking at the version number. I think it is better if a developer of a package makes a conscious and explicit decision on what is supported and what should work with the current release. Anything else seems to be a guesswork, which may be working in 95% of the cases, but then it would give surprising side-effects and unintended consequences in other cases.

The goal of this proposal is to give the developer of a package the opportunity to indicate whether their 1.0 promotion is breaking. I think the need for this is a consequence of the Dart community convention to apply a shifted semver to pre-1.0 versions, which communicates more information to the community during extended package development and creates the possibility of many dependent packages prior to 1.0 release.

Another potential solution would be to just declare 1.0 releases as always non-breaking and require breaking promotions to go straight to 2.0, but that seems harder to shoehorn on top of the current ecosystem.

I think the dependencies_override is a good way for a consumer of the libraries to override a package's dependency if it is lagging behind.

The consumer of a package may not even know what the package does, if it's a second-level dependency. I think that dependencies_override should be a last resort, and not something that package consumers should have to resort to in common cases. Every successful plugin author will eventually have this painful 1.0 promotion decision, and I think they're in better position than package consumers or dependent packages to know whether their 1.0 promotion was intended to be breaking or not.

[jonasfj]

there's still going to be a period of time where the package is version locked -- there's no first mover advantage for dependent packages to accept the new version because doing so would make them incompatible with the herd

This is where version ranges like >=0.42.0 <2.0.0 becomes useful. Now you can be first mover (in adapting 1.0.0) without becoming incompatible with the herd.

As long as you know that there is no breaking change in 1.0.0. This should be advertised in CHANGELOG and README, ideally along with the suggestion to use version ranges for maximum compatibility.

Note. Version ranges spanning multiple major versions can also be used when you know the breakage doesn't affect the part of the API your package uses.

But I feel like "I haven't made a breaking API change in a long time and don't plan to" is a meaningful point in the life cycle of a plugin that could be used to surface higher-quality plugins.

I think my reservation is with using the 1.0.0 version number for communicating that you think the API is so stable that you won't be breaking it anytime soon.

You'll see some people argue that releases should be allowed to carry both a version number and a release name (or code name)... I guess there is an argument with that one shouldn't communicate stability and compatibility using the same numbers :)

My initial reaction is that a simple imperfect solution is safer, when the fundamental flaw can't be fixed.. I'm thinking that our fundamental flaw here is that we attempt to signal compatibility and stability with the same number.

[jonasfj]

@jakemac53, @natebosch, any thoughts?

[natebosch]

I think this would be more cost than it's worth. The value it provides is limited - it is useful at a single point in a package lifecycle, and the value is diminished the fewer published packages exist that depend on a package using this features. I think most packages have few dependents. The cost would be high - this is somewhat complex to implement and very complex to document and try to convince enough of the community that it's worthwhile to learn and use.

[collinjackson]

I think this would be more cost than it's worth. The value it provides is limited - it is useful at a single point in a package lifecycle

I would argue that it has value over a long period of time; without this change, popular packages like package:http might stay pre-1.0 for a long time because of the work involved in releasing a 1.0 version. This makes it harder for dependent package authors to know whether the maintainer wants to allow dependent packages.

I think most packages have few dependents.

I agree -- but some have a lot. Making 1.0 updates smoother would make it more common for packages to get to 1.0 before they have many dependencies, so users won't have to reach for dependency_overrides.

Another challenge of dependency_overrides is that it makes it hard for package authors to get critical updates and bug fixes out to users.

[isoos]

I would argue that it has value over a long period of time; without this change, popular packages like package:http might stay pre-1.0 for a long time because of the work involved in releasing a 1.0 version.

I don't see it that way. http could release 1.0.0 without any issue. Packages using http may not update immediately, but eventually most packages will update. If it happens to be API-compatible, then the clients of the libraries don't really care which version they are on.

Even a second-level dependency conflict is something that is manageable:

• A 1.0.0 depends on http: ^0.12.0
• A 1.0.1 depends on http: ^1.0.0
• B 1.0.0 depends on http ^0.12.0
• C depending on both A and B may resolve only to http ^0.12.0 and A 1.0.0, but can use an override to use http 1.0.0 (and A 1.0.1).

Neither of the packages needs strong coordination (e.g. release timing, version constraint to use), and doesn't need the introduction of surprising behaviour.

[amirh]

I agree these situations can be fixed by the app developer (C) adding dependency_overrides, but at this point it may become too painful for app developers (they get an obscure error rooted in a transitive dependencies they don't know about, and they need to figure out they can use dependency_overrides, which I believe is not very well known).

Another player in this game is Flutter, which unfortunately does not follow semver (and is also pinning some packages to specific versions which may cause other kinds of pain here).

In the scenario you described imagine that then comes a new Flutter version with a breaking change that breaks A (historically we had multiple instances where this was done mistakenly, e.g a Flutter release requires some plugins to tweak a gradle file). A 1.0.2 is released to fix the problem, but C is pinned down to A 1.0.0, and is now potentially getting some obscure Gradle compile error after upgrading Flutter.

[sigurdm]

@jonasfj and I discussed this a bit.
The problem is real.
But none of us are happy in meddling with the idea that a package has a single semver version number.

Instead we could consider the idea of a 'stability-bit' you can set on a package.
This bit indicates that the package (at its newest version) is considered ready for use in production.

That would free the version number to indicate breaking/patch change levels. And separate out the stability aspect of the version number.

One question is if users can learn to use this bit instead of the version number, when checking a package for stability.

[kevmoo]

Agreed w/ @sigmundch and @jonasfj – WE should not mess w/ the semantics of semver!

My only add-on. This bit should only be available to pre-v1 packages. I'd argue we still want a world where v1+ is considered stable!

[jonasfj]

I'd argue we still want a world where v1+ is considered stable!

Yeah, it might also be weird to add a stability bit.. one could make the argument that if we want versioning and stability to be separate then don't use semver. And if we want to change stability without breaking API, don't use semver.

I'm curious how the 1.0.0 migration goes, if it's not too bad -- maybe having the version be breaking is fine. Every other solution makes things more complicated.