tl;dr

  • Update: this guidance is specific Dart packages. I'll write about Dart apps soon.
  • Read about the Pub Versioning Philosophy.
  • If your package uses new features in the SDK or packages, make sure you set an inclusive minimum version constraint – >= X.Y.Z – to avoid breaking folks who have not yet upgraded.
  • Set exclusive maximum version constraints – <X.Y.Z – to make sure major releases of the SDK and packages don't break your code.
  • Understand how pre-v1.0 are versioned with regard to breaking changes.
  • Take a look at pubspec files in our SDK to understand how we handle versioning. Example: http package pubspec.yaml.

New features and minimum version constraints

Dart v1.3 is coming soon. String has learned a few tricks since v1.2, specifically:
  • String padLeft(int newLength, String padding)
  • String padLeft(int newLength, String padding)
  • String trimLeft()
  • String trimRight()
Awesome, right? I can imagine package authors doing the following:
  1. Download Dart 1.3 Editor and SDK
  2. Replace all internal hacks with new String functions.
  3. Release?
No! #3 should be: Update your pubspec.yaml.

pubspec.yaml content

In the Dart Editor

Setting the minimum SDK to 1.3.0 tells the pub tools and your users the users that a package requires at least v1.3 of the Dart SDK. Better to get an error from pub install or pub update than to get static warnings or runtime errors about missing functions.

You'll also notice more than just an inclusive minimum SDK constraint – >=1.3.0 – there's also an exclusive maximum SDK constraint – <2.0.0.

Our promise it to follow semantic versioning for the SDK and our shipped packages. The short version:
  • For a version X.Y.Z
  • Increases to Y indicate new features, but no breaking changes.
  • Increases to X indicate breaking changes.
It should be safe to set your maximum SDK version to be any release up to, but not including, v2.0.

Packages and pre-v1.0

The same applies to packages managed by the Dart team, like unittest, args, path, etc.

We have a number of packages that are pre-v1.0 – unittest is a great example.

unittest is one of our oldest and most used packages. We'd really like to lock it down and clean it up before releasing something we consider v1.0. 

If you look at the changelog for unittest, you'll see a number of breaking changes between v0.9.2 and v0.10.0.

For pre-v1.0 packages, we bump the versioning logic up a level, so for version 0.Y.Z, changes to Y are breaking and changes to Z are non-breaking.

Look again at the changelog for unittest. You'll see a number of features marked as DEPRECATED. These are things that will likely go away – stop working – in v0.11.0 of unittest.

If you want to make sure you code does not suddenly break, you should set a version constraint on unittest of something like >=0.10.0 <0.11.0.

Am I missing new hotness?

A lot of folks dislike setting maximum version constraints.

I always want to be running the new hotness!

I don't want to miss out on new features!

pub upgrade is your friend.

If you run pub upgrade from the console or within the Dart Editor, you'll see useful hints when there are newer versions of packages than what you currently specify.


You can then carefully update and check version constraints before you release.

If you want to visualize a complex package with many dependencies, check out pubviz.

Happy hacking!