Migration guide for package:flutter_lints

src/docs/release/breaking-changes/flutter-lints-package.md

@@ -0,0 +1,129 @@
+---
+title: Introducing package:flutter_lints
+description: Migrate to package:flutter_lints to get the latest set of recommended lints, which encourage good coding practices.
+---
+
+## Summary
+
+The [`package:flutter_lints`][] defines the latest set of recommended lints that
+encourage good coding practices for Flutter apps, packages, and plugins. Projects
+created with `flutter create` using Flutter version 2.3.0-12.0.pre or newer are
+already enabled to use the latest set of recommended lints. Projects created
+prior to that version can upgrade to it with the instructions in this guide.
+
+## Context
+
+Prior to the introduction of `package:flutter_lints`, the Flutter framework
+shipped with a set of lints defined in [`analysis_options_user.yaml`][] that was
+used by the [dart analyzer][] to identify code issues if a Flutter project
+didn't define a custom `analysis_options.yaml` file. Since `analysis_options_user.yaml`
+was tied to a particular framework version, it was difficult to evolve without
+breaking existing apps, packages, and plugins. As a result of that, the lints
+defined in `analysis_options_user.yaml` are heavily outdated. To fix this,
+`package:flutter_lints` was created. The package versions the lint set to enable
+evolving it without breaking existing projects. Since the package builds on
+Dart's [`package:lints`][] it also aligns the lints recommended for Flutter
+projects with the rest of the Dart ecosystem.
+
+## Migration guide
+
+Follow these steps to migrate your Flutter project to use the latest recommended
+lints from `package:flutter_lints`:
+
+Add a dev_dependency on `package:flutter_lints` to your project's `pubspec.yaml`
+by running `flutter pub add --dev flutter_lints` in the root directory of the
+project.
+
+Create an `analysis_options.yaml` file in the root directory of your project
+(next to the `pubspec.yaml` file) with the following content:
+```yaml
+include: package:flutter_lints/flutter.yaml
+```
+
+The newly activated lint set may identify some new issues in your code. To find
+them, open your project in an [IDE with Dart support][] or run `flutter analyze`
+on the command line. You may be able to fix some of the reported issues
+automatically by running `dart fix --apply` in the root directory of your
+project.
+
+### Existing custom analyzer_options.yaml file
+
+If your project already has a custom `analysis_options.yaml` file at its root,
+add `include: package:flutter_lints/flutter.yaml` to it at the top to activate
+the lints from `package:flutter_lints`. If your `analysis_options.yaml` already
+contains an `include:` directive you have to decide whether you want to keep
+those lints or whether you want to replace it with the lints from
+`package:flutter_lints` because the Dart analyzer only supports one `include:`
+directive per `analysis_options.yaml` file.
+
+## Customizing the lints
+
+The lints activated for a given project can be further customized in the
+`analysis_options.yaml` file. This is shown in the example file below, which is
+a reproduction of the `analysis_options.yaml` file generated by `flutter create`
+for new projects.
+
+```yaml
+# This file configures the analyzer, which statically analyzes Dart code to
+# check for errors, warnings, and lints.
+#
+# The issues identified by the analyzer are surfaced in the UI of Dart-enabled
+# IDEs (https://dart.dev/tools#ides-and-editors). The analyzer can also be
+# invoked from the command line by running `flutter analyze`.
+
+# The following line activates a set of recommended lints for Flutter apps,
+# packages, and plugins designed to encourage good coding practices.
+include: package:flutter_lints/flutter.yaml
+
+linter:
+  # The lint rules applied to this project can be customized in the
+  # section below to disable rules from the `package:flutter_lints/flutter.yaml`
+  # included above or to enable additional rules. A list of all available lints
+  # and their documentation is published at
+  # https://dart-lang.github.io/linter/lints/index.html.
+  #
+  # Instead of disabling a lint rule for the entire project in the
+  # section below, it can also be suppressed for a single line of code
+  # or a specific dart file by using the `// ignore: name_of_lint` and
+  # `// ignore_for_file: name_of_lint` syntax on the line or in the file
+  # producing the lint.
+  rules:
+    # avoid_print: false  # Uncomment to disable the `avoid_print` rule
+    # prefer_single_quotes: true  # Uncomment to enable the `prefer_single_quotes` rule
+
+# Additional information about this file can be found at
+# https://dart.dev/guides/language/analysis-options
+```
+
+## Timeline
+
+Landed in version: 2.3.0-12.0.pre<br>
+In stable release: not yet
+
+## References
+
+Documentation:
+
+* [`package:flutter_lints`][]
+* [Package dependencies][]
+* [Customizing static analysis][]
+
+Relevant issues:
+
+* [Issue 78432 - Update lint set for Flutter applications][]
+
+Relevant PRs:
+
+* [Add flutter_lints package][]
+* [Integrate package:flutter_lints into templates][]
+
+[Add flutter_lints package]: {{site.github}}/flutter/packages/pull/343
+[`analysis_options_user.yaml`]: {{site.github}}/flutter/flutter/blob/master/packages/flutter/lib/analysis_options_user.yaml
+[Customizing static analysis]: {{site.dart-site}}/guides/language/analysis-options
+[dart analyzer]: {{site.dart-site}}/guides/language/analysis-options
+[IDE with Dart support]: {{site.dart-site}}/tools#ides-and-editors
+[Integrate package:flutter_lints into template]: {{site.github}}/flutter/flutter/pull/81417
+[Issue 78432 - Update lint set for Flutter applications]: {{site.github}}/flutter/flutter/issues/78432
+[`package:flutter_lints`]: {{site.pub}}/packages/flutter_lints
+[`package:lints`]: {{site.pub}}/packages/lints
+[Package dependencies]: {{site.dart-site}}/tools/pub/dependencies

src/docs/release/breaking-changes/index.md

@@ -13,9 +13,11 @@ release, and listed in alphabetical order:
 ### Not yet released to stable
 
 * [Default Scrollbars on Desktop][]
+* [Introducing package:flutter_lints][]
 * [ThemeData's accent properties have been deprecated][]
 
 [Default Scrollbars on Desktop]: /docs/release/breaking-changes/default-desktop-scrollbars
+[Introducing package:flutter_lints]: /docs/release/breaking-changes/flutter-lints-package
 [ThemeData's accent properties have been deprecated]: /docs/release/breaking-changes/theme-data-accent-properties
 
 ### Reverted changes