The Life of a Lint

Lint States

Proposed

A lint begins its life as a proposal which is pending until accepted.

Accepted

After discussion and sufficient agreement within the team, a proposed lint becomes accepted.

An accepted lint is ready for implementation.

Experimental

Lints can be marked experimental.

Reasons a lint might be marked experimental include a lint

  • being tentatively introduced
  • having unknown value
  • having incomplete semantics
  • having outstanding (fixable) false positives or
  • that might be known to be temporary.

Stable

Stable lints are lints whose semantics and implementation are considered complete. False positives (that are not known, accepted and documented limitations of lint semantics) are considered bugs and fixing them should be prioritized. False negatives may be bugs or enhancements (depending on semantics).

Deprecated

Deprecated lints are lints that we plan to remove.

Reasons for deprecation include:

  • semantics that don't make sense with current language semantics (e.g., null-safety)
  • stale advice
  • poor performance or
  • poor user experience (e.g., too many false positives).

Removed

Lints we no longer support are removed.

In general removal is preceded by a period of deprecation.

State Transitions

Implementation

Once a lint proposal is accepted, it is safe to implement. A change that lands a new lint should have a corresponding CHANGELOG entry.

Deprecation

Implemented lints can be deprecated.

Deprecating lints that are in common lint sets (e.g., in package:lints can be impactful so should be done with care.

(NOTE: A change that deprecates an existing lint should have a corresponding CHANGELOG entry.)

Marking Stable

Experimental lints should aspire to be stable. An experimental lint is a candidate for stable when it has

  • complete semantics
  • complete implementation (with no false-positives)
  • established long-term value (e.g., inclusion in a recommended lint set)

Removal

Deprecated or experimental lints can be removed. A stable lint should be deprecated before removal.

(NOTE: A change that removes an existing lint should have a corresponding CHANGELOG entry.)