Create a gist now

Instantly share code, notes, and snippets.

@nex3 /barback.md
Last active Aug 29, 2015

What would you like to do?
Barback Compatibility Policy

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.

Internal changes

These do not affect the API that either transformers or pub use. For these, we bump barback’s build version (ex: 0.14.20.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.

Backwards-compatible changes

These extend the API but not in a breaking way. For these, we bump barback’s patch version (ex: 0.14.20.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".

Backwards-incompatible changes

When the API that either transformers or pub uses changes in an incompatible way, we bump barback’s minor version (ex: 0.14.20.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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment