diff --git a/src/docs/release/breaking-changes/flutter-lints-package.md b/src/docs/release/breaking-changes/flutter-lints-package.md new file mode 100644 index 00000000000..5c1d1fb6c1e --- /dev/null +++ b/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
+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 diff --git a/src/docs/release/breaking-changes/index.md b/src/docs/release/breaking-changes/index.md index cb63adad269..8b8d0b1d18a 100644 --- a/src/docs/release/breaking-changes/index.md +++ b/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