Skip to content

Commit

Permalink
Tweak the README a bit and add a section on evolution process. (dart-…
Browse files Browse the repository at this point in the history
…lang/lints#46)

* Tweak the README a bit and add a section on evolution process.

* Fix typo.

* "pre-defined" -> "predefined".
  • Loading branch information
munificent authored Jul 30, 2021
1 parent b165f7f commit 1c8b030
Showing 1 changed file with 36 additions and 31 deletions.
67 changes: 36 additions & 31 deletions pkgs/lints/README.md
Original file line number Diff line number Diff line change
@@ -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.
Expand All @@ -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.
Expand All @@ -39,51 +36,59 @@ 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
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
`use_full_hex_values_for_flutter_colors` (included in [`package:flutter_lints`]).
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
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
Expand Down

0 comments on commit 1c8b030

Please sign in to comment.