Skip to content

Release process

Jump to bottom
Bob Nystrom edited this page Jun 16, 2026 · 7 revisions

The formatter reaches users in two main ways:

  • From the Dart SDK, by running dart format. This uses a version of dart_style that is copied into the Dart SDK.

  • As a library, by depending on the dart_style package and using the public API it exposes. (The package also exposes a command line tool you can invoke using dart run or dart pub global activate, but that's rarely used).

Most users run the formatter through the Dart or Flutter SDKs, so "shipping" the formatter is usually synchronized with a Dart SDK release. In particular, since the formatter internally encodes the language versions it supports, we need to update the formatter whenever a new Dart SDK is going to be released.

Shipping a new version of the formatter means both rolling it into the Dart SDK and publishing a new version of the package onto pub.dev, in that order. It is usually synchronized to an upcoming Dart SDK release.

Support the latest language version

When a new Dart SDK is about to ship, it means the highest supported language version is about to increase. The formatter shipped with that SDK obviously needs to support that language version.

  1. In lib/src/dart_formatter.dart, increment latestLanguageVersion to the upcoming Dart language version.

  2. If there are any language changes in that version, ensure that the formatter supports them and has tests.

  3. Make sure that the lower bound of dart_style's dependency on analyzer is high enough to ensure that it picks a version of analyzer that supports the new language. In practice, this usually means bumping the dependency to require the latest analyzer version.

Roll dart_style into the Dart SDK

Once a package is published to pub, it's very hard to unpublish it. We want to make sure it doesn't have any regressions or unanticipated style changes. We validate that by testing inside Google before publishing on pub. The Dart SDK is automatically rolled into Google's monorepo on a frequent basis, so by rolling a commit of dart_style into the SDK, we get internal testing on a very large corpus of Dart code.

When we have a commit of the formatter that we are ready to ship, the first step is rolling it into the Dart SDK:

  1. In the Dart SDK repo, update the "dart_style_rev" line in the DEPS file to point to the new commit hash.

TODO: If there are style changes that necessitate updating the pre-built SDK, describe how to do that.

  1. If there are user-visible changes, then update the SDK's CHANGELOG with those changes. You can mostly just copy the relevant entries from dart_style's CHANGELOG over.

  2. Upload that change and send it out for review (rnystrom@, kallentu@, athom@, or anyone on Dart eng-prod can review it).

    If the formatter change includes support for some new language feature, this may cause CFE golden file tests to fail on the trybots. That's because those tests run the formatter if it succeeds or fall back to using the unformatted output if it fails. CFE folks often commit tests for new language features before the formatter supports them, so those golden files will be unformatted. When rolling a new formatter in, those tests can now be successfully formatted, so the (now formatted) expected output doesn't match the (unformatted) golden file.

    If you see test failures like this, the output will have a command to run to update the golden files. Run that, verify that it's just formatting changes, and upload those fixes with the change.

  3. Once you get approval and the bots are green, land the change.

Wait a few days for the SDK to get rolled into Google's monorepo and see if there are any problems. If so, fix them. Otherwise, this commit is now ready to be published...

Publish a new version of dart_style

When a version of the formatter is rolled into the Dart SDK, we should also publish it. That way, there is always a version of the dart_style library available for tools like code generators that matches the formatting behavior of dart format.

  1. From a local clone of dart_style on the main branch, run:

    $ dart run grinder ship

    That runs the tests and some other sanity checks to make sure the release looks good. It then updates the version number in the pubspec to remove the -wip part.

  2. Assuming everything passes and looks good, create and upload a new branch with the changes and send out a PR for review (@munificent, @kallentu, or @natebosch). At this point, the changes should literally just be tweaking the version number in two places. You may also want to clean up the CHANGELOG a bit.

  3. Once the PR is approved, squash and merge it to main. A GitHub action will leave a comment on the PR telling you how to publish a version. That comment will contain the new version number. Click that number to open a page to create a new GitHub release for the version.

  4. Copy the relevant entries from the CHANGELOG into the release notes and then click "Publish release". That creates a new GitHub release for the version which in turn kicks off another Github action that automatically publishes that version to pub.dev.

  5. Go to pub.dev, search for "dart_style" and bask in the glory of having shipped a new version to the world.

Clone this wiki locally