Development process

This page describes how changes to dart_style are committed to the repo and how new versions are released and rolled out. If you don't contribute to the formatter, it's probably not useful to you.

Language versioning style changes

Most changes to the formatter are changes to the style rules it applies. Unless the change is a fix for obviously broken output (like reordering code or dropping code on the floor), the change should be language versioned.

This means that the style change should only apply to Dart code whose language version is the next upcoming Dart SDK version number of later. This way, users don't have their formatting spontaneously change on them when they upgrade to a new Dart SDK. Instead, it's only when they edit their SDK constraint and opt in to the latest language version that they also see the style changes.

For example, let's say the most recent release of the Dart SDK is 3.9.0. You make a style change in the formatter. That change should only apply to files whose language version is 3.10 or later. If the language version is 3.9 or earlier, the previous style should be applied.

This means that making style changes almost always increases the complexity of the formatter because it needs to support the old and new style. Eventually, we hope to drop support for particularly old styles.

Landing a change

The dart_style repo mostly follows a typical GitHub workflow. Changes are uploaded to branches and the author sends a pull request. Code review happens on the pull request and, once approved, the author squashes and merges the PR onto the main branch.

The main branch should always be in a shippable state. Any change that requires multiple commits before the formatter is back into a usable state should be done either on a branch or behind some sort of flag so that users aren't impacted until the work is completely done.

We also need to keep track of what changes have landed and whether a given change has been shipped. To do that:

Update the CHANGELOG

Every PR that affects something user-visible should also add an entry to the CHANGELOG file describing the change.

Update the package version

When a PR lands a change, it should update the dart_style version number in the pubspec.yaml file to indicate that there are unpublished changes. If the dart_style version does not end in -wip, then the repo should be exactly equal to the published dart_style package at that version.

Otherwise, the version ends in -wip, and the number preceding that is what the next published version number will be. If we see that the version ends in -wip, we know there are unpublished changes. The way that number is bumped from the previously published version depends on what kinds of changes have landed. For example, let's say the last published version was 1.2.3:

• If main has some unpublished minor non-breaking changes, then the pubspec's version would be 1.2.4-wip.

• If main has significant new features but no breaking changes, then the pubspec's version would be 1.3.0-wip.

• If main has a breaking change, then the version would be 2.0.0-wip.

We don't consider style changes to be "breaking" (otherwise, almost every change would be a breaking change), so most revisions to dart_style are patch releases. Breaking changes usually mean a breaking change to the library API or CLI options. More impactful style changes may necessitate a minor or major version increment.

When you land a change on main, make sure that you update the pubspec's version number as needed to reflect your change. Note that you'll only need to bump the -wip version the first time a change of a certain kind is landed. So if, for example, there are already minor changes and the pubspec's version is 1.2.4-wip, then you can land more minor changes without touching the version. You may need to change the number of an already--wip version if you are landing a change of greater caliber than previous ones. So if the version is 1.2.4-wip and you land the first significant new feature, you'd bump it to 1.3.0-wip.

Update the internal version number

If you changed the pubspec version number, then you also need to change the corresponding number in lib/src/cli/formatter_options.dart. This is what's printed when you run dart format --version.