identify place to host canonical lints

[pq]

Let the bike-shedding begin!

To start, here are a few proposals.

Proposal 1 : (new) package:canonical

Name

package:canonical (https://pub.dev/packages?q=canonical 👍 )

Structure

lib/
  analysis_options.yaml
  canonical_1.0.0.yaml
  recommend/
    canonical_1.0.0.yaml
    analysis_options.yaml

A few details:

• analysis_options.yaml just include:s latest the same way pedantic currently does
• lib/recommend/canonical_1.0.0.yaml has an include: of the root (scoring) lints and adds the recommended ones to it

Sample Uses

To get the latest scoring lints:

include: package:canonical/analysis_options.yaml

or to pin to a version:

include: package:canonical/analysis_options.1.0.0.yaml

Turning the dial up to the recommended lints looks like:

include: package:canonical/recommend/analysis_options.yaml
include: package:canonical/recommend/analysis_options.1.0.0.yaml

Proposal 2: package:pedantic

Alternatively, we could use the existing package:pedantic. (Cheers @munificent for this one.)

Structure

lib/
  analysis_options.yaml
  pedantic_1.0.0.yaml
  pub/
    pedantic_1.0.0.yaml
    analysis_options.yaml
  recommend/
    pedantic_1.0.0.yaml
    analysis_options.yaml

In this case the "root" one would probably have to remain the current google style.

Sample Uses

To get google style:

include: package:pedantic/analysis_options.yaml
include: package:pedantic/analysis_options.1.0.0.yaml

Pub scoring:

include: package:pedantic/pub/analysis_options.yaml
include: package:pedantic/pub/analysis_options.1.0.0.yaml

Recommended:

include: package:pedantic/recommend/analysis_options.yaml
include: package:pedantic/recommend/analysis_options.1.0.0.yaml

/fyi @bwilkerson @munificent @natebosch @jakemac53 @davidmorgan @mit-mit @lrhn for input

[natebosch]

I think this should not be a pub package, this should be something shipped in the SDK. I don't see any way that we can enable scoring lints by default (even if we don't do it to start with) if they are defined in a package.

[jakemac53]

I think this should not be a pub package, this should be something shipped in the SDK. I don't see any way that we can enable scoring lints by default (even if we don't do it to start with) if they are defined in a package.

We could make it so that pub lish warns if you don't add the scoring lints? Regular apps and non-published packages though would be harder to point at these lints to be sure.

Putting it in the SDK is not without downsides either - it is harder to evolve, adds more friction to updating your sdk, and makes it so users on old sdks don't see the updated scoring lits. Users on the pre-release sdks will also see a different set than pub.dev sees (assuming it uses stable).

[jakemac53]

As far as the original proposal - I would be somewhat inclined to move the top level analysis_options.yaml under pub_score directory? It isn't clear to me that those are the pub scoring lints with the current structure.

I would also probably go for recommended instead of recommend.

[munificent]

If we put it in the SDK, that means the set of lints can spontaneously change on users when they upgrade SDKs. If we put it in a package, it gets pinned in their lockfile and upgraded when they choose.

[natebosch]

it gets pinned in their lockfile and upgraded when they choose.

If this is a goal it excludes showing lints to folks without config. I think that work we do now which encourages more config today it's a step in the wrong direction - early opt-in is one thing but additional config like a package dep that is temporary feels like noise and debt to clean up later.

I think it's important that we can provide help and tips to users even if they didn't start their project with stagehand or know to add some magic config to their analysis_options.yaml and pubspec.yaml.

[natebosch]

set of lints can spontaneously change on users when they upgrade SDKs

We could choose which lints to show based on language version. That's a mechanism that would be very likely to be useful down the road anyway.

[jakemac53]

If we put it in the SDK, that means the set of lints can spontaneously change on users when they upgrade SDKs. If we put it in a package, it gets pinned in their lockfile and upgraded when they choose.

Fwiw, I think this is actually a negative for the package option. At least when it comes to scoring related lints I think we would always want all users to see exactly what pub will be scoring on right now, and not have to do anything special to update. It is possibly more likely that shipping it with the sdk would achieve that more consistently.

We also don't have a built in way of updating a single package, so upgrading lints becomes tied in with updating all dependencies. Granted the sdk option has a similar problem of it being tied to the sdk update.

[NatoBoram]

What are canonical lints? Which rules are included? Could they be added to effective_dart?

[mit-mit]

If we put it in the SDK, that means the set of lints can spontaneously change on users when they upgrade SDKs. If we put it in a package, it gets pinned in their lockfile and upgraded when they choose.

For scoring lints, I think we have to move towards a breaking change like notification process anyway, given how impactful they are to package authors.

[davidmorgan]

FWIW I suggest package:analysis_options if we end up with a new package.

Re: pinning, having versioned yaml files within the package allows people to choose between pinning and not pinning, even if it auto updates with the SDK.

[lrhn]

If we distribute the package with the SDK, this will be the first package that comes with the SDK. We'll need new resolution logic in the Pub tool (it's a package which is not fetched from pub), and we'll need to decide whether to move it into the pub cache, or whether to link directly to it in the SDK repo (I'd probably go for the former).

And if someone wants to use a newer the package with an older SDK, they're completely out of luck.

I think I'd prefer to just publish it as a normal package. I don't want to mix it with package:pedantic.

We can make Pub recommend a pub get when it sees that your analysis options package is not up-to-date (older than what the Pub tool itself uses).

I'm probably fine with having the analyzer use a default set of lints (which is the newest recommended set) if there is no lint configuration at all, or only lint-x :ignore configurations. If there is any positive lint configured, then drop the defaults and use the configuration.

[mit-mit]

Pub supports SDK constraints (Flutter uses them extensively), so it's not very much work if we wanted to.

dependencies:
  canonical:
    sdk: dart

Regarding versioning, we could still allow referencing older versions explicitly, e.g. something like this for selecting the 2.12 scoring lints?

analysis_options.yaml:

include: package:canonical/scoring/2.12/analysis_options.yaml