search

w3c / webref

Machine-readable references of terms defined in web browser specifications
https://w3c.github.io/webref/
MIT License
303 stars 73 forks source link

Be able to determine "stability" of CSS features #640

Open gsnedders opened 2 years ago

gsnedders commented 2 years ago

Arguably an issue split between here and web-specs, but there are cases where we might want multiple levels of specs.

For example, the CSS WG's "Requirements for Responsible Implementation of CSS" include a notion of stability, defined as:

A CSS feature is considered unstable until its specification has reached the Candidate Recommendation (CR) stage in the W3C process. In exceptional cases, the CSSWG may additionally, by an officially-recorded resolution, add pre-CR features to the set that are considered safe to release for broad use. See § 4 Safe to Release pre-CR Exceptions.

As such, there's a need to be able to determine whether a CSS feature is contained within a spec that has reached CR or not.

At the moment, font-variant-alternates appears in CSS Fonts 4 (and hence /tr/css/css-fonts.json), but that's a pre-CR spec, hence is an unstable feature, whereas font-variant-ligatures appears in CSS Fonts 3 (a REC) as well, but only appears here in /tr/css/css-fonts.json as part of CSS Fonts 4. There's no way between here and web-specs to determine that the latter is "safe" to implement but the former isn't.

This can also get more complex, for example with properties where the value space is expanded in a later pre-CR level.

tidoust commented 2 years ago

Arguably an issue split between here and web-specs, but there are cases where we might want multiple levels of specs.

That is already somewhat doable but it is hard to come up with a rule that both allows us to maintain webref with minimal manual intervention and account for nuances that some groups follow. We've trying to strike a middle ground and, by definition, our middle ground will miss some of these nuances. Where would you want to surface the notion of stability? In MDN?

On top of stability, I note that the same CSS Snapshot spec defines the notion of Rough interoperability and CSS Fonts 4 falls within the list of modules with rough interoperability. If the notion of stability somehow appears in extracts, we may also need to surface the notion of rough interoperability. Or would that not be needed?

The middle ground that we have so far in web-specs is through the notion of currentSpecification. For CSS specs, that's essentially the level that the shortname (without level) returns. Typically, https://www.w3.org/TR/css-fonts/ currently returns Level 4, that's what we use as current specification in web-specs, along with the next CSS Fonts 5 level (currently a delta spec).

That notion of current specification is entirely in the hands of the working groups that develop the specs. The CSS WG can decide that css-fonts should rather redirect to the more stable level 3 of CSS Fonts for instance. If css-fonts redirected to level 3, current specification would become that level (and that would produce the css-fonts.json extract) and we would add CSS Fonts 4 and CSS Fonts 5 as future levels with their own versioned extracts in webref.

Of course, the meaning of "current" for a working group can be orthogonal to stability, so we may indeed need to integrate additional dimensions to web-specs/webref.

gsnedders commented 2 years ago

Where would you want to surface the notion of stability? In MDN?

My immediate goal is to create a list of CSS properties that are safe to release, and those which are not yet, and those with unsafe-to-release changes in the value space in safe-to-release properties.

On top of stability, I note that the same CSS Snapshot spec defines the notion of Rough interoperability and CSS Fonts 4 falls within the list of modules with rough interoperability. If the notion of stability somehow appears in extracts, we may also need to surface the notion of rough interoperability. Or would that not be needed?

In the short term at least, I'm not interested in that, not least because it's clearly much harder (it involves both a subjective judgement and finding a record of CSS WG consensus).

gsnedders commented 2 years ago

I guess the extreme option is "what if we include the latest version of every specification on w3.org/TR/ in tr in webref" (instead of merely the latest version of every specification series—which I realise is an oversimplification); now, I can well imagine not wanting to include these in the curated output (as this would involve much more manual work!), but it might be useful to go to this extreme on main? Ultimately we're still well under the GitHub Actions limit time, and I doubt this would push us that far?