From 7405e0998b9878586d42a732de50c3f5b5155fbb Mon Sep 17 00:00:00 2001 From: Robert Nystrom Date: Wed, 28 Jul 2021 15:40:23 -0700 Subject: [PATCH 1/3] Tweak the README a bit and add a section on evolution process. --- README.md | 61 ++++++++++++++++++++++++++++++------------------------- 1 file changed, 33 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index d52bdfd..b23f8ce 100644 --- a/README.md +++ b/README.md @@ -1,22 +1,20 @@ [![pub package](https://img.shields.io/pub/v/lints.svg)](https://pub.dev/packages/lints) [![Build Status](https://github.com/dart-lang/lints/workflows/validate/badge.svg)](https://github.com/dart-lang/lints/actions?query=branch%3Amain) -# Official Dart lint rules. +# Official Dart lint rules The Dart linter is a static analyzer for identifying possible problems in your Dart source code. More than a hundred [linter rules][rules] are available, checking anything from potential typing issues, coding style, and formatting. - -The current `package:lints` contains the official selections of lints that the -Dart team encourages using. +This package, `lints`, contains the lint settings recommended by the Dart team. Two sets of lints are available: -* ***Core lints***: Lints that help identify critical issues that are likely to +* **Core lints**: Lints that help identify critical issues that are likely to lead to problems when running or consuming Dart code. All code should pass these lints. -* ***Recommended lints***: Lints that help identify additional issues that may +* **Recommended lints**: Lints that help identify additional issues that may lead to problems when running or consuming Dart code, and lints that enforce writing Dart using a single, idiomatic style and format. All code is encouraged to pass these lints. The recommended lints include all the core lints. @@ -27,8 +25,7 @@ When creating new Dart project using the [`dart create`][dart create] command, the lints from `package:lints` are enabled by default. When uploading a package to the [pub.dev] package repository, packages are -[awarded pub points][scoring] depending on whether they pass at least the 'core' -lints (note: the recommended lints automatically include all core lints). +[awarded pub points][scoring] based on how many of the 'core' lints pass. For documentation on the individual lints, see the [linter rules][rules] page on dart.dev. @@ -39,26 +36,26 @@ For new apps created with `dart create`, the lints are enabled by default. For existing apps or packages, take these steps to enable these lints: -1. In a terminal, located at the root of your package, run this command: +1. In a terminal, located at the root of your package, run this command: -```terminal -dart pub add --dev lints -``` + ```terminal + dart pub add --dev lints + ``` -2. Create a new `analysis_options.yaml` file, next to the pubspec, that includes -the lints package: +2. Create a new `analysis_options.yaml` file, next to the pubspec, that + includes the lints package: -```yaml -include: package:lints/recommended.yaml -``` + ```yaml + include: package:lints/recommended.yaml + ``` -or: + or: -```yaml -include: package:lints/core.yaml -``` + ```yaml + include: package:lints/core.yaml + ``` -## Customizing the pre-defined lint sets +## Customizing the predefined lint sets You can customize the pre-defined lint sets, both to disable one or more of the lints included, or to add additional lints. For details see [customizing static @@ -67,7 +64,7 @@ analysis]. ## Migrating from `package:pedantic` In migrating from the pre-defined lint sets provided by the [`package:pedantic`], -you get static analysis coverage from 29 additional lints. There are, however, +you get static analysis coverage from 29 additional lints. There are, however, 6 lints which the pedantic package includes which are not included in the pre-defined lint sets provided by the lints package: `always_declare_return_types`, `prefer_single_quotes`, @@ -77,13 +74,21 @@ pre-defined lint sets provided by the lints package: To keep any of these lints enabled, add them to your [analysis options][customizing static analysis]. -## Submitting Feedback +## Evolving the lint sets + +The Dart language changes and the ecosystem continues to develop new best +practices, so the lint sets must be periodically updated to reflect the best way +we know to write Dart code. The informal process we use is: + +1. Anyone can file an [issue] to discuss a potential change to a lint set. (A + change here means adding or removing a lint from one or both sets. If you + want to discuss implementing an entirely new lint, the place to suggest that + is at the [linter repo].) Feedback is welcome from any Dart user. -Feedback is welcome! If you want to propose an existing lint for inclusion here, -check to see if there is already an open [issue] and chime in. If there is not, -please start a conversation with a new issue. If you have questions about existing -lints or have an idea for a new one, please file an issue on the [linter repo]. +2. Periodically, a group of Dart and Flutter team members meet to review the + suggests and decide what to adopt. +3. The lists are updated and a new version of the package is published. [dart create]: https://dart.dev/tools/dart-tool [scoring]: https://pub.dev/help/scoring From 2604a36052794969d84d6ad21c708952dd199673 Mon Sep 17 00:00:00 2001 From: Robert Nystrom Date: Wed, 28 Jul 2021 15:56:05 -0700 Subject: [PATCH 2/3] Fix typo. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index b23f8ce..edbb840 100644 --- a/README.md +++ b/README.md @@ -86,7 +86,7 @@ we know to write Dart code. The informal process we use is: is at the [linter repo].) Feedback is welcome from any Dart user. 2. Periodically, a group of Dart and Flutter team members meet to review the - suggests and decide what to adopt. + suggestions and decide what to adopt. 3. The lists are updated and a new version of the package is published. From bdbf97b4f93ce5acbb7dec92de87b6765549161f Mon Sep 17 00:00:00 2001 From: Robert Nystrom Date: Wed, 28 Jul 2021 17:20:14 -0700 Subject: [PATCH 3/3] "pre-defined" -> "predefined". --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index edbb840..db0340f 100644 --- a/README.md +++ b/README.md @@ -57,16 +57,16 @@ For existing apps or packages, take these steps to enable these lints: ## Customizing the predefined lint sets -You can customize the pre-defined lint sets, both to disable one or more of the +You can customize the predefined lint sets, both to disable one or more of the lints included, or to add additional lints. For details see [customizing static analysis]. ## Migrating from `package:pedantic` -In migrating from the pre-defined lint sets provided by the [`package:pedantic`], +In migrating from the predefined lint sets provided by the [`package:pedantic`], you get static analysis coverage from 29 additional lints. There are, however, 6 lints which the pedantic package includes which are not included in the -pre-defined lint sets provided by the lints package: +predefined lint sets provided by the lints package: `always_declare_return_types`, `prefer_single_quotes`, `sort_child_properties_last` (included in [`package:flutter_lints`]), `unawaited_futures`, `unsafe_html`, and