Skip to content

Commit 1c8b030

Browse files
authored
Tweak the README a bit and add a section on evolution process. (dart-archive/lints#46)
* Tweak the README a bit and add a section on evolution process. * Fix typo. * "pre-defined" -> "predefined".
1 parent b165f7f commit 1c8b030

File tree

1 file changed

+36
-31
lines changed

1 file changed

+36
-31
lines changed

pkgs/lints/README.md

Lines changed: 36 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,20 @@
11
[![pub package](https://img.shields.io/pub/v/lints.svg)](https://pub.dev/packages/lints)
22
[![Build Status](https://github.com/dart-lang/lints/workflows/validate/badge.svg)](https://github.com/dart-lang/lints/actions?query=branch%3Amain)
33

4-
# Official Dart lint rules.
4+
# Official Dart lint rules
55

66
The Dart linter is a static analyzer for identifying possible problems in your
77
Dart source code. More than a hundred [linter rules][rules] are available,
88
checking anything from potential typing issues, coding style, and formatting.
9-
10-
The current `package:lints` contains the official selections of lints that the
11-
Dart team encourages using.
9+
This package, `lints`, contains the lint settings recommended by the Dart team.
1210

1311
Two sets of lints are available:
1412

15-
* ***Core lints***: Lints that help identify critical issues that are likely to
13+
* **Core lints**: Lints that help identify critical issues that are likely to
1614
lead to problems when running or consuming Dart code. All code should pass these
1715
lints.
1816

19-
* ***Recommended lints***: Lints that help identify additional issues that may
17+
* **Recommended lints**: Lints that help identify additional issues that may
2018
lead to problems when running or consuming Dart code, and lints that enforce
2119
writing Dart using a single, idiomatic style and format. All code is encouraged
2220
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,
2725
the lints from `package:lints` are enabled by default.
2826

2927
When uploading a package to the [pub.dev] package repository, packages are
30-
[awarded pub points][scoring] depending on whether they pass at least the 'core'
31-
lints (note: the recommended lints automatically include all core lints).
28+
[awarded pub points][scoring] based on how many of the 'core' lints pass.
3229

3330
For documentation on the individual lints, see the [linter rules][rules] page on
3431
dart.dev.
@@ -39,51 +36,59 @@ For new apps created with `dart create`, the lints are enabled by default.
3936

4037
For existing apps or packages, take these steps to enable these lints:
4138

42-
1. In a terminal, located at the root of your package, run this command:
39+
1. In a terminal, located at the root of your package, run this command:
4340

44-
```terminal
45-
dart pub add --dev lints
46-
```
41+
```terminal
42+
dart pub add --dev lints
43+
```
4744
48-
2. Create a new `analysis_options.yaml` file, next to the pubspec, that includes
49-
the lints package:
45+
2. Create a new `analysis_options.yaml` file, next to the pubspec, that
46+
includes the lints package:
5047
51-
```yaml
52-
include: package:lints/recommended.yaml
53-
```
48+
```yaml
49+
include: package:lints/recommended.yaml
50+
```
5451
55-
or:
52+
or:
5653
57-
```yaml
58-
include: package:lints/core.yaml
59-
```
54+
```yaml
55+
include: package:lints/core.yaml
56+
```
6057
61-
## Customizing the pre-defined lint sets
58+
## Customizing the predefined lint sets
6259
63-
You can customize the pre-defined lint sets, both to disable one or more of the
60+
You can customize the predefined lint sets, both to disable one or more of the
6461
lints included, or to add additional lints. For details see [customizing static
6562
analysis].
6663
6764
## Migrating from `package:pedantic`
6865
69-
In migrating from the pre-defined lint sets provided by the [`package:pedantic`],
70-
you get static analysis coverage from 29 additional lints. There are, however,
66+
In migrating from the predefined lint sets provided by the [`package:pedantic`],
67+
you get static analysis coverage from 29 additional lints. There are, however,
7168
6 lints which the pedantic package includes which are not included in the
72-
pre-defined lint sets provided by the lints package:
69+
predefined lint sets provided by the lints package:
7370
`always_declare_return_types`, `prefer_single_quotes`,
7471
`sort_child_properties_last` (included in [`package:flutter_lints`]),
7572
`unawaited_futures`, `unsafe_html`, and
7673
`use_full_hex_values_for_flutter_colors` (included in [`package:flutter_lints`]).
7774
To keep any of these lints enabled,
7875
add them to your [analysis options][customizing static analysis].
7976
80-
## Submitting Feedback
77+
## Evolving the lint sets
78+
79+
The Dart language changes and the ecosystem continues to develop new best
80+
practices, so the lint sets must be periodically updated to reflect the best way
81+
we know to write Dart code. The informal process we use is:
82+
83+
1. Anyone can file an [issue] to discuss a potential change to a lint set. (A
84+
change here means adding or removing a lint from one or both sets. If you
85+
want to discuss implementing an entirely new lint, the place to suggest that
86+
is at the [linter repo].) Feedback is welcome from any Dart user.
8187
82-
Feedback is welcome! If you want to propose an existing lint for inclusion here,
83-
check to see if there is already an open [issue] and chime in. If there is not,
84-
please start a conversation with a new issue. If you have questions about existing
85-
lints or have an idea for a new one, please file an issue on the [linter repo].
88+
2. Periodically, a group of Dart and Flutter team members meet to review the
89+
suggestions and decide what to adopt.
8690
91+
3. The lists are updated and a new version of the package is published.
8792
8893
[dart create]: https://dart.dev/tools/dart-tool
8994
[scoring]: https://pub.dev/help/scoring

0 commit comments

Comments
 (0)