Add the formatter changes to the CHANGELOG.

Change-Id: Ib8e0e8e99f77ebfa00f53eb3e2b4442b60b392ff
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/394571
Commit-Queue: Leaf Petersen <[email protected]>
Auto-Submit: Bob Nystrom <[email protected]>
Reviewed-by: Leaf Petersen <[email protected]>

CHANGELOG.md

@@ -82,6 +82,137 @@ main() {
 - Add the experimental `omit_obvious_property_types` lint rule.
 - Deprecate the `package_api_docs` lint rule.
 
+#### Dart format
+
+The formatter implements a [new style][tall style] better suited for the kind of
+declarative code that many Dart users are writing today. The new style looks
+similar to the style you get when you add trailing commas to argument lists,
+except that now the formatter will add and remove those commas for you.
+
+The `dart format` command [uses the language version][formatter lang version] of
+each input file to determine which style it gets. If the language version is 3.6
+or lower, the code is formatted with the old style. If 3.7 or later, it gets the
+new tall style.
+
+You typically control the language version by [setting a min SDK constraint in
+your package's pubspec][versioning]. This means that when you update the SDK
+constraint in your pubspec to move to 3.7, you are also opting in to the new
+style.
+
+In order to correctly determine the language version of each file it formats,
+`dart format` (like other `dart` commands) looks for a `package_config.json`
+file surrounding the files being formatted. This means that **you need to run
+`dart pub get` before formatting code in your package.** If you have format
+checks in your continuous integration server, you'll want to make sure it runs
+`dart pub get` too.
+
+We don't intend to support both styles indefinitely. At some point in the
+future when most of the ecosystem is on 3.7 or later, support for the old style
+will be removed.
+
+[tall style]: https://github.com/dart-lang/dart_style/issues/1253
+
+[versioning]: https://dart.dev/guides/language/evolution
+
+[formatter lang version]: https://github.com/dart-lang/dart_style/issues/1402
+
+In addition to the new formatting style, a number of other changes are included,
+some of them breaking:
+
+* **Project-wide page width configuration.** By long request, you can now
+  configure your preferred formatting page width on a project-wide basis. When
+  formatting a file, the formatter will look in the file's directory and any
+  surrounding directories for an `analysis_options.yaml` file. If it finds one,
+  it looks for YAML like so:
+
+  ```yaml
+  formatter:
+    page_width: 123
+  ```
+
+  If it finds a page width matching that schema, then the file is formatted
+  using that width. Since the formatter will walk the surrounding directories
+  until it finds an `analysis_options.yaml` file, this can be used to globally
+  set the page width for an entire directory, package, or even collection of
+  packages. Since `analysis_options.yaml` files already support an `include`
+  key to reference other `analysis_options.yaml` files, you can define a single
+  configuration and share it across a number of packages.
+
+* **Opting out a region of code from formatting.** In code formatted using the
+  new style, you can use a pair of special marker comments to opt a region of
+  code out of automated formatting:
+
+  ```dart
+  main() {
+    this.isFormatted();
+    // dart format off
+    no   +   formatting
+      +
+        here;
+    // dart format on
+    formatting.isBackOnHere();
+  }
+  ```
+
+  The comments must be exactly `// dart format off` and `// dart format on`.
+  A file may have multiple regions, but they can't overlap or nest.
+
+  This can be useful for highly structured data where custom layout helps the
+  reader understand the data, like large lists of numbers.
+
+* **Overriding the page width for a single file.** In code formatted
+  using the new tall style, you can use a special marker comment to control the
+  page width that it's formatted using:
+
+  ```dart
+  // dart format width=30
+  main() {
+    someExpression +
+        thatSplitsAt30;
+  }
+  ```
+
+  This comment must appear before any code in the file and must match that
+  format exactly. The width set by the comment overrides the width set by any
+  surrounding `analysis_options.yaml` file.
+
+  This feature is mainly for code generators that generate and immediately
+  format code but don't know about any surrounding `analysis_options.yaml`
+  that might be configuring the page width. By inserting this comment in the
+  generated code before formatting, it ensures that the code generator's
+  behavior matches the behavior of `dart format`.
+
+  End users should mostly use `analysis_options.yaml` for configuring their
+  preferred page width (or do nothing and continue to use the default page width
+  of 80).
+
+* **Breaking change: Remove support for `dart format --fix`.** Instead, use
+  `dart fix`. It supports all of the fixes that `dart format --fix` could apply
+  and many more.
+
+* **Treat the `--stdin-name` name as a path when inferring language version.**
+  When reading input on stdin, the formatter still needs to know its language
+  version to know what style to apply. If the `--stdin-name` option is set, then
+  that is treated as a file path and the formatter looks for a package config
+  surrounding that file path to infer the language version from.
+
+  If you don't want that behavior, pass in an explicit language version using
+  `--language-version=`, or use `--language-version=latest` to parse the input
+  using the latest language version supported by the formatter.
+
+  If `--stdin-name` and `--language-version` are both omitted, then the
+  formatter parses stdin using the latest supported language version.
+
+* **Rename the `--line-length` option to `--page-width`.** This is consistent
+  with the public API, internal implementation, and docs, which all use "page
+  width" to refer to the limit that the formatter tries to fit code into.
+
+  The `--line-length` name is still supported for backwards compatibility, but
+  may be removed at some point in the future. You're encouraged to move to
+  `--page-width`. Use of this option (however it's named) is rare, and will
+  likely be even rarer now that project-wide configuration is supported, so
+  this shouldn't affect many users.
+
 ## 3.6.0
 
 ### Language