Barback is in a unique position in the Dart ecosystem, in that it's a package upon which the SDK itself places a version constraint. In addition, it's still relatively young and undergoing considerable change. This document outlines the policy for making changes to barback while still maintaining a high degree of compatibility with the Dart ecosystem.
These do not affect the API that either transformers or pub use. For these, we bump barback’s build version (ex: 0.14.2
→ 0.14.2+1
). This is within the version range that both pub and other packages allow, so everything works with both versions of barback. Pub’s barback constraint is not touched.
These extend the API but not in a breaking way. For these, we bump barback’s patch version (ex: 0.14.2
→ 0.14.3
). This is within the version range that other packages allow, so they won’t need to be updated. Pub’s constraint on barback is expanded to one patch above that version. For example, it might go from ">=0.14.0 <0.14.3"
to ">=0.14.0 <0.14.4"
.
When the API that either transformers or pub uses changes in an incompatible way, we bump barback’s minor version (ex: 0.14.2
→ 0.15.0
). Pub’s constraint on barback is expanded to one patch above that version. For example, it might go from ">=0.14.0 <0.14.3"
to ">=0.14.0 <0.15.1"
.
We will then change pub to detect at runtime which version of barback was selected. It will expose a matching API to transformer plug-ins. Pub will maintain this compatibility until the Dart 2.0 SDK is released.