[Meta] Ship the new formatting style and migrate to it

[munificent]

Since last year, we have been rewriting the Dart formatter (the dart format command and dart_style package where its implementation lives) to apply a style that works better for the kinds of declarative code Dart users are writing today and fix a list of long-standing style bugs. The rewrite is mostly done and it's time now to prepare to ship it.

This meta-issue tracks work to ship the new style and migrate code owned by the Dart and Flutter teams to that style.

Migrate code to pass in a language version to the formatter API

The new formatter will use language version to determine whether you get the old or new style. The DartFormatter constructor now takes an optional parameter where you can pass in the language version. In a future version of dart_style, that parameter will become mandatory.

Before we can do that, the Dart SDK (and the various packages it pulls in) need to be migrated to start passing that in:

• Analyzer code should start passing a language version to dart_style #56685
• dart2js code should start passing a language version to dart_style #56686
• CFE code should start passing a language version to dart_style #56687
• Please start passing in a language version to dart_style dartdoc#3871
• Please start passing in a language version to dart_style http#1304
• Please start passing in a language version to dart_style mockito#764
• Please start passing in a language version to dart_style web#300

For the packages developed outside of the Dart SDK repo, these changes then need to be rolled in:

• Roll dartdoc into Dart SDK
• Roll http into Dart SDK
• Roll mockito into Dart SDK
• Roll web into Dart SDK

Make the language version mandatory

While users are migrating to dart_style 2.3.7 and passing in the language version, we can start working on the new major version of dart_style. Since we're bumping the major version, this enables us to make some other planned breaking changes:

• Make the language version parameter to DartFormatter() mandatory and bump the dart_style package's major version. (Make the language version parameter to DartFormatter mandatory. dart_style#1563)
• Remove support for dart format –fix. The dart fix command is a strict superset and the new style doesn't support fixes. (Remove support for fixes and --fix. dart_style#1564)
• Update the old CLI in the dart_style package to the dart format CLI. When the dart format command was added, we took the opportunity to clean up the CLI options and arguments (for example, you no longer have to pass -w to tell it to write files). However, if you globally activate the dart_style package, the installed binary still uses the old CLI options. We should change the package's CLI to be the same as the dart format command's. (Remove the old CLI options and executables. dart_style#1565)

Note that the new style is still behind an experiment flag, so this is a "major" version only because of the API changes.

Ship the new style

In addition to the above changes, we will probably still be fixing style issues and tweaking the output. Once those changes have mostly settled down, it's time to actually ship the new style and flip the experiment flag.

• (Ship the "tall-style" experiment. dart_style#1578) Use language version instead of the experiment flag to determine what style you get. Flip the "tall-style" flag to always be on.

Roll into the Dart SDK and migrate the SDK

Rolling the new dart_style into the SDK is challenging because some Dart code in the SDK will already be at the language version where the new style applies. Probably the core libraries, and maybe some other packages, runtime code, etc. As soon as the new dart_style lands, that code will be incorrectly using the old style. (Code in packages that are still using an older language version is fine because that will still use the old style.)

We can't reformat that code in the same commit that rolls in the new dart_style, because the presubmit uses a pre-built version of the SDK. So, I think the easiest approach is:

• (https://dart-review.googlesource.com/c/sdk/+/391320) Temporarily disable the format check in the presubmit script.
• (https://dart-review.googlesource.com/c/sdk/+/391263) Roll the new dart_style into the Dart SDK.
• Regenerate and land a pre-built SDK with the new dart_style.
• Reformat code in the Dart SDK. Run the formatter on the whole Dart repo (minus third_party and multitests). Send out some number of giant code reviews to land it all. Let the team know what they may need to update any in-progress changes they have to the new style.
• (Handle the new formatting style in the static error test updater #57042) Update the static error test updater to handle indented comments.
• Re-enable the format check in the presubmit. At this point, everything in the SDK repo should have the right style and we should have a pre-built SDK with a new enough formatter to validate that.
• (https://dart-review.googlesource.com/c/sdk/+/394571) Update the SDK CHANGELOG. Describe the new style and language version selection for it. Also describe the new support for opting regions of code out of formatting.
• Publish a new version of dart_style.

Migrate Flutter

It's to be determined how this will happen.

Announce

Once we're certain the new style will ship in a version of the Dart and Flutter SDKs, we can announce it:

• Announce that a new style is coming in the new Dart SDK. Explain how language versioning will work.