Settle on a process for deprecating lints

[pq]

Follow-up from dart-archive/linter#1178 (comment) most recently but this has come up before as well, we should settle on a process for deprecating lints.

[bwilkerson]

One possibility would be to create a new Maturity named deprecated. The doc generator could add a banner and our analysis could generate a warning for lints with that maturity. That wouldn't support telling users what to do about it (in the referenced case it's to replace the old lint with two new lints) nor give us a way to create a quick-fix. I suppose we could have a subclass of Maturity that has additional information.

[pq]

The latest analyzer has a new Maturity.deprecated/ . dart-archive/linter#1276 takes advantage of it.

[pq]

Closing the loop on process, are we agreed that we will use the deprecated lint maturity w/ a doc noting that deprecated lints are subject to removal in a future release?

@bwilkerson : do we have any boilerplate in analyzer (or elsewhere) we could crib?

As for documentation, I'm thinking a separate page on http://dart-lang.github.io/linter/lints/ that we can link to from deprecated lint docs. Examples of good docs like this would be welcome too btw...

@srawlins, @a14n, @MichaelRFairhurst : thoughts?

[srawlins]

Is there any reason not to remove a lint immediately? (or, like, the very next release after deprecating)? I thought dartanalyzer ignored unknown lint rule names found in analyzer_options.yaml.

[pq]

Is there any reason not to remove a lint immediately?

I guess I'd like to leave the door open for conversation. Dropping some immediately would have no impact (e.g., ones made redundant by default analysis) but for those that would, I guess immediate removal feels sudden and could possibly bum folks out.

[bwilkerson]

are we agreed that we will use the deprecated lint maturity w/ a doc noting that deprecated lints are subject to removal in a future release?

I agree that that should be part of the process, but I think we need to do a little more. We should probably add some support to the analysis of analysis options files so that uses of deprecated lints are flagged in some way.

do we have any boilerplate in analyzer (or elsewhere) we could crib?

Not that I'm aware of. Deprecating lints is a little different than deprecating APIs.

Is there any reason not to remove a lint immediately? (or, like, the very next release after deprecating)? I thought dartanalyzer ignored unknown lint rule names found in analyzer_options.yaml.

Yes, dartanalyzer will ignore unknown lints when analyzing Dart code. It will generate a diagnostic if the analysis options file is analyzed, which might impact users that take advantage of that. Echoing Phil's comment, it seems rude to not give people time to react to the announcement that a lint is going to be removed. How long we need to wait is something I don't know.

[pq]

We should probably add some support to the analysis of analysis options files so that uses of deprecated lints are flagged in some way.

👍

Opened #35291 to track.

[pq]

FWIW: deprecated lint validation has landed on the analyzer branch and should be available in server in the next dev build (or as soon as the analyzer branch is folded back into master).

[pq]

/fyi @csells

[FMorschel]

@pq I'd say this can actually be closed by now. WDYT?

[pq]

Thanks!