Tweak the README a bit and add a section on evolution process. (#46)
* Tweak the README a bit and add a section on evolution process.
* Fix typo.
* "pre-defined" -> "predefined".
diff --git a/README.md b/README.md
index d52bdfd..db0340f 100644
--- a/README.md
+++ b/README.md
@@ -1,22 +1,20 @@
[](https://pub.dev/packages/lints)
[](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 @@
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,37 +36,37 @@
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
+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`],
-you get static analysis coverage from 29 additional lints. There are, however,
+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
@@ -77,13 +74,21 @@
To keep any of these lints enabled,
add them to your [analysis options][customizing static analysis].
-## Submitting Feedback
+## Evolving the lint sets
-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].
+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.
+
+2. Periodically, a group of Dart and Flutter team members meet to review the
+ suggestions 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
