From 2b4f9969a5f91766acca4d22b03dd9b29895c50a Mon Sep 17 00:00:00 2001 From: Michael Goderbauer Date: Thu, 6 May 2021 14:55:48 -0700 Subject: [PATCH 1/5] Migration guide for package:flutter_lints --- .../breaking-changes/flutter-lints-package.md | 128 ++++++++++++++++++ src/docs/release/breaking-changes/index.md | 2 + 2 files changed, 130 insertions(+) create mode 100644 src/docs/release/breaking-changes/flutter-lints-package.md 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..61038c9036a --- /dev/null +++ b/src/docs/release/breaking-changes/flutter-lints-package.md @@ -0,0 +1,128 @@ +--- +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 practises for Flutter apps, packages, and plugins. Projects +created with `flutter create` after Flutter version 2.xx 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 make it easier +to evolve the set of recommended lints, `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 universe. + +## 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 previously undiscovered issues in +your code. To find them, run `flutter analyze` in the root directory of your +project and fix all reported issues. 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.xx
+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]: https://dart.dev/guides/language/analysis-options +[dart analyzer]: https://dart.dev/guides/language/analysis-options +[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`]: https://pub.dev/packages/flutter_lints +[`package:lints`]: https://pub.dev/packages/lints +[Package dependencies]: https://dart.dev/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 From d9c0ca26f059a1f8cab0b18c56b84cf15e5c0243 Mon Sep 17 00:00:00 2001 From: Michael Goderbauer Date: Thu, 6 May 2021 15:05:36 -0700 Subject: [PATCH 2/5] wording --- .../release/breaking-changes/flutter-lints-package.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/docs/release/breaking-changes/flutter-lints-package.md b/src/docs/release/breaking-changes/flutter-lints-package.md index 61038c9036a..77420dc96c0 100644 --- a/src/docs/release/breaking-changes/flutter-lints-package.md +++ b/src/docs/release/breaking-changes/flutter-lints-package.md @@ -19,11 +19,11 @@ 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 make it easier -to evolve the set of recommended lints, `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 universe. +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 universe. ## Migration guide From f8abf363f2da4dc9c7415befe7cbbf6bcc5ab008 Mon Sep 17 00:00:00 2001 From: Michael Goderbauer Date: Thu, 6 May 2021 16:52:34 -0700 Subject: [PATCH 3/5] pq review --- .../release/breaking-changes/flutter-lints-package.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/docs/release/breaking-changes/flutter-lints-package.md b/src/docs/release/breaking-changes/flutter-lints-package.md index 77420dc96c0..d4c225a0efa 100644 --- a/src/docs/release/breaking-changes/flutter-lints-package.md +++ b/src/docs/release/breaking-changes/flutter-lints-package.md @@ -6,24 +6,24 @@ description: Migrate to package:flutter_lints to get the latest set of recommend ## Summary The [`package:flutter_lints`][] defines the latest set of recommended lints that -encourage good coding practises for Flutter apps, packages, and plugins. Projects +encourage good coding practices for Flutter apps, packages, and plugins. Projects created with `flutter create` after Flutter version 2.xx 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 +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 +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 universe. +projects with the rest of the Dart universe. ## Migration guide From 28335dbcf371a65e39ab79bdd3f313020881eba8 Mon Sep 17 00:00:00 2001 From: Michael Goderbauer Date: Mon, 10 May 2021 09:53:53 -0700 Subject: [PATCH 4/5] mit & shams review --- .../breaking-changes/flutter-lints-package.md | 23 ++++++++++--------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/src/docs/release/breaking-changes/flutter-lints-package.md b/src/docs/release/breaking-changes/flutter-lints-package.md index d4c225a0efa..bba25db6fd4 100644 --- a/src/docs/release/breaking-changes/flutter-lints-package.md +++ b/src/docs/release/breaking-changes/flutter-lints-package.md @@ -23,7 +23,7 @@ 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 universe. +projects with the rest of the Dart ecosystem. ## Migration guide @@ -40,10 +40,10 @@ Create an `analysis_options.yaml` file in the root directory of your project include: package:flutter_lints/flutter.yaml ``` -The newly activated lint set may identify some previously undiscovered issues in -your code. To find them, run `flutter analyze` in the root directory of your -project and fix all reported issues. You may be able to fix some of the reported -issues automatically by running `dart fix --apply` in the root directory of your +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 @@ -53,7 +53,7 @@ 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:` +`package:flutter_lints` because the Dart analyzer only supports one `include:` directive per `analysis_options.yaml` file. ## Customizing the lints @@ -119,10 +119,11 @@ Relevant PRs: [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]: https://dart.dev/guides/language/analysis-options -[dart analyzer]: https://dart.dev/guides/language/analysis-options +[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`]: https://pub.dev/packages/flutter_lints -[`package:lints`]: https://pub.dev/packages/lints -[Package dependencies]: https://dart.dev/tools/pub/dependencies +[`package:flutter_lints`]: {{site.pub}}/packages/flutter_lints +[`package:lints`]: {{site.pub}}/packages/lints +[Package dependencies]: {{site.dart-site}}/tools/pub/dependencies From e17ca43bae373b504bb6c960b724099baf7e3c7d Mon Sep 17 00:00:00 2001 From: Michael Goderbauer Date: Tue, 18 May 2021 17:00:07 -0700 Subject: [PATCH 5/5] add version info --- .../release/breaking-changes/flutter-lints-package.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/docs/release/breaking-changes/flutter-lints-package.md b/src/docs/release/breaking-changes/flutter-lints-package.md index bba25db6fd4..5c1d1fb6c1e 100644 --- a/src/docs/release/breaking-changes/flutter-lints-package.md +++ b/src/docs/release/breaking-changes/flutter-lints-package.md @@ -7,9 +7,9 @@ description: Migrate to package:flutter_lints to get the latest set of recommend 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` after Flutter version 2.xx 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. +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 @@ -97,7 +97,7 @@ linter: ## Timeline -Landed in version: 2.xx
+Landed in version: 2.3.0-12.0.pre
In stable release: not yet ## References