Skip to content

Release process

Jump to bottom
Bob Nystrom edited this page Jun 17, 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. Then from the root directory of the SDK:

  2. Re-build the SDK:

    $ gclient sync -D && ./tools/build.py -m release create_sdk

  3. Run the pkg tests to make sure everything is working:

    $ python3 tools/test.py -m release dart_style

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

  5. Re-format the SDK with the new style changes. Run:

    $ dart tools/format_sdk.dart

    Re-formatting the SDK on a roll ensures that the SDK stays on the current style. Also, once the dart_style roll lands in the repo, users developing against the SDK will have the latest formatter, but the pre-built SDK used for the presubmit checks will be out of sync for a couple of days. Having the code already reformatted to the new style will enable that presubmit to gracefully degrade because it will see the developer's code matches what's already been committed and doesn't represent a new style violation.

  6. Upload that change and send it out for review (rnystrom@, kallentu@, nbosch@, 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.

  7. 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 continue...

Update the pre-built SDK to include the new formatter

The Dart SDK includes a number of presubmit checks, including one that verifies any changed code is properly formatted. That check uses a pre-built version of the Dart SDK that needs to be updated so that the presubmit isn't demanding an out of date style.

  1. Wait a couple of days for a new dev channel build of the SDK to be created.

  2. In the DEPS file, find the "sdk_tag" key. Update its value to version: followed by the version from the previous step. For example:

      "sdk_tag": "version:3.13.0-190.0.dev",

  3. Send that change out for review.

Once this lands, the style produced by dart format in the SDK and the style validated by the presubmit check are back in sync with each other.

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. Once we know a version of dart_style has successfully rolled into the Dart SDK repo, Flutter, and google3, it's ready to be published:

  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