Document browser support policy based on Baseline Widely Available

[GrimLink]

I recently updated the Fylgja Stylelint Config and was surprised to find that the rule media-feature-range-notation: "context" was added in v32 of stylelint-config-standard.

While Safari supports the css media range syntax, support is still limited to the latest two minor versions (16.4 and 16.5) https://caniuse.com/css-media-range-syntax.
Meaning most users on iOS will not have support for this feature.

This means that anyone using v32 of stylelint-config-standard who wants to support Safari must either disable the rule or use a tool to compile their code back to the older syntax.

I'm not sure whether stylelint should add rules that are so new that they still require tools to work in all evergreen browsers. I feel that stylelint should not force users of a linting tool to use new syntax when support is still too new.

I would like to see stylelint wait until there is broader support before adding rules like this one to the config standard.
A similar suggestion was made in the issue that added this rule, #275 (comment)

Please consider:

• Removing the rule media-feature-range-notation: "context, until support is beter, e.g. until the next major Safari release
• Or adding documentation to the README, pointing out that the Stylelint config standard uses rules that have very early browser support.

[ybiquitous]

@GrimLink Thanks for opening the issue.

I'm against removing media-feature-range-notation: "context" because we would need to re-add the rule in the future. And the removal would instead confuse other people who already benefit from the rule.

• Or adding documentation to the README, pointing out that the Stylelint config standard uses rules that have very early browser support.

Rather, I agree with the idea of deciding our browser support policy and documenting it. But if so, we must discuss how to decide and operate the policy. This might be a complicated discussion. 🤔

[jeddy3]

But if so, we must discuss how to decide and operate the policy

If we have a guiding principle, we can use our judgement case-by-case rather than have a rigid browser support policy.

There are many different ways to write styles. Around 23.0.0, we geared this config towards those writing modern CSS. I think we should continue to do this, but let's explore what this means.

Two groups are writing modern CSS, those writing:

• very modern CSS with syntax-lowering tools (like postcss-preset-env and Lightning CSS)
• pretty modern CSS without syntax-lowering tools (sometimes called buildless)

We can try to cater to both groups. How's about this as a guiding principle for this config:

"To help people write as modern as possible CSS without penalising those not using syntax-lowering tools"

We can interpret how that's applied on a case-by-case basis by weighing up the caniuse data against the benefits of that particular syntax, e.g. does it fix a shortcoming with the older syntax or bring more consistency? This will likely mean we delay adding a rule until it has support in popular versions of evergreen browsers. Those writing very modern CSS can turn the rule on for themselves until it the syntax has broader browser support.

It's a more pragmatic position than the "supported in all evergreen browsers" one we used in #275 (comment).

How does that sound?

[ybiquitous]

Thanks for summing up. That makes sense to me. And adding the guideline as follows to README sounds very nice. 👍🏼

"To help people write as modern as possible CSS without penalising those not using syntax-lowering tools"

If adopting this guideline, we will need to consider caniuse.com before adding a new rule for modern syntax. For example, "Usage relative" is a good tool to do that. 👍🏼

-- https://caniuse.com/css-media-range-syntax

[jeddy3]

Thanks for pointing out the usage relative view on caniuse. I wasn't aware of it until now. It's definitely a good tool to help us judge!

[Mouvedia]

Rather, I agree with the idea of deciding our browser support policy and documenting it.

If we ever do that, it should be an upper limit that helps us choose default values and not something that triggers the addition of rules.

i.e.
is wrong: X is supported well enough now let's add rule Y
is OK: based on our browser support matrix we are picking this X default for rule Y

If adopting this guideline, we will need to consider caniuse.com before adding a new rule for modern syntax.

That should be mentioned somewhere on https://stylelint.io/developer-guide/rules.
This seems like common sense though.

…a more pragmatic position…

If we were to set the threshold at which we start our evaluation Id say something like at least 80% usage and support for these:

last 1 Chrome version
Firefox ESR
last 2 Safari major versions

[romainmenke]

It would make sense to align this with the Baseline definition.
This definition is still in flux but I think it aligns with the intention here.

Currently there is consensus that the Baseline definition should :

• cover all engines
• cover a very large majority of end users

In practice it will mean that a feature must have shipped in all engines since X time or X number of versions.

It is easy for users if you can say : "we use Baseline as a guide when adding new rules" because over time there will be shared understanding of what that means.

The marketing pages for Baseline are outdated, but recent work can be found here : https://github.com/web-platform-dx/web-features

[romainmenke]

updated definition for baseline : https://developer.mozilla.org/en-US/blog/baseline-evolution-on-mdn/

[jeddy3]

It is easy for users if you can say : "we use Baseline as a guide when adding new rules" because over time there will be shared understanding of what that means.

SGTM.

[ybiquitous]

@romainmenke Thanks for your sharing Baseline. I agree with following the Baseline. 👍🏼

I guess we have two Baseline options, and we need to choose one from them:

• Widely available

  A widely available feature has been in multiple browsers for years. It works with many browsers and devices, even ones that aren't yet up to date with the latest browser releases.

• Newly available

  A newly available feature works in the latest browsers, but may not work with older browsers and devices. Consider your site's audience carefully before using a newly available feature.

Ref https://developer.mozilla.org/en-US/docs/Glossary/Baseline/Compatibility

Now, I lean toward Widely available because it allows people to learn new features. But a downside may cause lint errors in projects needing to support old browsers. This is a trade-off, but I think the benefit of telling new features wins. To prevent lint errors, people can just turn off a problematic rule.

[Mouvedia]

I would wait for the results of web-platform-dx/web-features#208 before using their definitions.
I like where they are going with it in web-platform-dx/web-features#174.
see also https://github.com/web-platform-dx/web-features/blob/e572a5c17c69ae5f1c6acd51efb812b06fd61251/docs/baseline.md?plain=1#L153
I could make a custom browserslist—maybe generated by a script—based on these findings and the features we target.

[romainmenke]

I would wait for the results of web-platform-dx/web-features#208 before using their definitions.

I think the issues are outdated.
They just published an updated definition a few days ago that is the result of that research.

[Mouvedia]

1. baseline
   1. list the features
   2. add the missing ones
   3. pick an approach (e.g. 30+ months)
2. browserlist
   1. create a script to generate the list
   2. add as a npm script
   3. update https://stylelint.io/maintainer-guide/releases
3. stylelint-config-standard
   1. review config
   2. change config accordingly
   3. update README

[Mouvedia]

@ybiquitous can you change the title of the issue?
I don't have the right to do so.
e.g. "Establish our browser support policy based on baseline"

[ybiquitous]

I just changed the issue title.

[jeddy3]

It seems the general consensus is to adopt baseline: widely available.

I've labelled this issue as a documentation change.

It could be as simple as changing:

It extends stylelint-config-recommended and turns on additional rules to enforce modern conventions found in the CSS specifications.

To:

"It extends stylelint-config-recommended and turns on additional rules to enforce modern conventions found in the CSS specifications and within Baseline Widely Available.