External Package Maintenance

Versioning Packages

Bumping versions

Dart packages have two varieties of versioning schemes. We use semver with a variation that the numbers are shifted to the right if the package is not stable enough to reach a 1.0.0 release. Note that the Dart team culture was previously to keep packages at 0.x for a long time, whereas now we prefer to publish 1.0.0 as soon as feasible to avoid confusion over these patterns.

• For packages that are not yet stable: 0.major.minor+patch.
• For most packages: major.minor.patch.

Never include a +1 on a version if the first number is not 0. For breaking changes, bump the major version. For new features, including all non-breaking API changes like introducing a new class, bump the minor version. For bug fixes, documentation changes, or any other change which doesn't impact calling code, bump the patch version.

Making a change

Any time the code in the repo does not match exactly the code of a version published on pub, both the pubspec.yaml and CHANGELOG.md should include a -dev version. We bump the version on the first change after a publish, even if we don't plan on publishing the code in that state or if the change doesn't impact consumers.

When opening a PR, check if the pubspec and CHANGELOG already have a -dev version listed. If there is already a version, check what variety of version bump it is from the previous published version and compare to the type for the change you are making. If necessary you can "upgrade" the version change, for instance if the current -dev version is a patch number higher than what is published, and you are adding a feature, rewrite the version into a minor version change from what is published.

If the version is not currently a -dev, perform the appropriate version bump and add a -dev. Add a section in the CHANGELOG to match. Include the -dev suffix in both places to avoid potential confusion about what versions are published. If the change has no external impact (for instance a safe refactoring or lint cleanup) it is OK to leave the CHANGELOG section empty. If the change has external impact add an entry to the section for that version.

Publishing a package

If there are any risky changes for a release, always sync the package into google3 before publishing so that it can be validated against a larger corpus of code.

• Open a PR which removes the trailing -dev from the version in both the pubspec and the changelog. It is OK to do this in the same PR as another change if that change should be published immediately.
• pub publish. Don't ignore any warnings or errors reported by pub unless you are completely confident they are safe to ignore.
• Add a git tag with the version that was published. Check other tags in the repo to decide whether to include a leading v in the tag. New repositories should prefer to include the v. In a mono repo, start the tag with the name of the package. For example build_runner-v1.7.0. Be sure to git push --tags after adding a tag.