Csswg-drafts: Versioning policy and backwards incompatible changes

[gsnedders]

I started writing this as a comment on #5111, but it seems like I've never actually posted an issue for all the times we've spoken about this. This also arguably has implications on #4770.

[It] seems useful, to distinguish [specs such as cascade-3] from other old RECs which are unmaintained and wrong. People should be reading cascade-4, but they're not going to run into problems if they read cascade-3. On the other hand, the same isn't true about reading CSS2.0 instead of CSS2.1.

Honestly this just touches on our inconsistent habits with versioning again. I would much rather we actually tackled the whole versioning issue generally (where level 1 is nowadays defined informatively in the CSS Snapshot with the superseded spec advised against; level 2 is defined by 2.1; level 3 is defined by the modules; etc.).

At the moment if we make a backwards incompatible change to Level 4, our practice is to make behaviour undefined/optional in L2 and L3 (and ignore L1), which means we have to republish a number of RECs with substantive changes each time we make a backwards incompatible change, and that number is only going to increase over time. We also have a long term ambition to fully obsolete CSS2, which will then lead to the question as to where the normative definition of Level 2 will live.

We have a number of options here, as I see it:

1. Continue down the status-quo, accepting republishing multiple RECs when we do make normative changes.
2. Rewrite the L[n] spec to define itself as a subset of those in L[n+1].
3. Make the L[n] spec define behaviour for all L[

[tabatkins]

We also have a long term ambition to fully obsolete CSS2, which will then lead to the question as to where the normative definition of Level 2 will live.

I don't think we will have a normative definition of Level 2 at that point. It'll be obsoleted just as much as CSS 1 is. We're not far from that point already.

At the moment if we make a backwards incompatible change to Level 4, our practice is to make behaviour undefined/optional in L2 and L3 (and ignore L1),

I don't think that's our practice, either?

CSS2 had a lot of stuff declared undefined near the end of its process, not because of backwards-incompatible changes in the level 3 module, but because the behavior wasn't yet consistent between browsers and so we couldn't get 2+ passes for tests for any reasonable defined behavior.

Since then, I don't think we've gone back and undefined things because of a change in later versions, have we? We sometimes remove things because we prefer the levels to not contradict each other, just for confusion-avoidance reasons, but there's no sense in which an earlier level is a meaningful artifact which an implementor can decide to support vs a later level. They're just previous versions of the current document, is all.

[gsnedders]

I don't think we will have a normative definition of Level 2 at that point. It'll be obsoleted just as much as CSS 1 is. We're not far from that point already.
…
We sometimes remove things because we prefer the levels to not contradict each other, just for confusion-avoidance reasons, but there's no sense in which an earlier level is a meaningful artifact which an implementor can decide to support vs a later level. They're just previous versions of the current document, is all.

Yet we define levels in Snapshot as:

Cascading Style Sheets does not have versions in the traditional sense; instead it has levels. Each level of CSS builds on the previous, refining definitions and adding features. The feature set of each higher level is a superset of any lower level, and the behavior allowed for a given feature in a higher level is a subset of that allowed in the lower levels. A user agent conforming to a higher level of CSS is thus also conformant to all lower levels.

To me this strongly implies we view support for each level as meaningful. Likewise, the fact we bother to define what Level 1 constitutes also implies we consider it a meaningful artifact; if it's in fact just a previous version of the document then surely there's no point in defining what Level 1 is?

CSS2 had a lot of stuff declared undefined near the end of its process, not because of backwards-incompatible changes in the level 3 module, but because the behavior wasn't yet consistent between browsers and so we couldn't get 2+ passes for tests for any reasonable defined behavior.

Since then, I don't think we've gone back and undefined things because of a change in later versions, have we?

I could swear we had; we've definitely upon occasion discussed making things undefined (which is equivalent to removing them, no?).

As a meta point: that the fairly new editor of CSS2 disagrees with others about what the WG policy is on maintaining older versions of spec text is says something about the WG, and it isn't good. We really need to better document (in a discoverable way!) cross-spec policy decisions for things like that.

[fantasai]

For maintained specs, yes, we try to make sure that lower levels are compatible with future work. This generally isn't too much work, since higher levels refine behavior or add features, they don't usually change things that were defined in earlier levels. In the rare cases where there's a change from what was specced previously, we go back and make sure the older spec is compatible with the future spec.

For unmaintaned specs, like CSS1, we mark the specs as obsolete and define that level as being, essentially, the set of features defined therein as defined by the higher level maintained specs.

So essentially, we're doing a combination of 1 and 2 from the OP, depending on whether we've obsoleted the spec or not.

[tabatkins]

To me this strongly implies we view support for each level as meaningful.

Yeah, that's some really funky text. It doesn't match the reality of how the WG treats its specs (or how any of the consumers of the specs - browsers, authors, etc - treat them). It should be fixed.

As a meta point: that the fairly new editor of CSS2 disagrees with others about what the WG policy is on maintaining older versions of spec text is says something about the WG, and it isn't good.

Granted, tho I'll note that in practice it isn't a big deal for almost anyone; everyone just looks at the latest spec that defines something and gets by fine with that. ^_^ You're in a pretty particular position where the precise semantics here do sorta matter.

But still, yeah, valid point.

[gsnedders]

For unmaintaned specs, like CSS1, we mark the specs as obsolete and define that level as being, essentially, the set of features defined therein as defined by the higher level maintained specs.

What's the disadvantage of doing this for all levels/modules? I am very much in favour of maintaining less spec text, even if it is generally not too much work (and it's more than just editorial work when we need to republish).

Yeah, that's some really funky text. It doesn't match the reality of how the WG treats its specs (or how any of the consumers of the specs - browsers, authors, etc - treat them). It should be fixed.

it does sound like you and @fantasai disagree here? Like, her view seems to be that the levels are meaningful?

[frivoal]

What's the disadvantage of doing this for all levels/modules?

I think we should generally do that to the level N module when the N+1 module reaches REC (or if the featureset of level N has been rearranged into multiple modules at N+1, when all these modules reach REC). Until then, as @fantasai said:

In the rare cases where there's a change from what was specced previously, we go back and make sure the older spec is compatible with the future spec.

For CSS2, that means we cannot declare it as superseded just yet, because not all its parts have a Level 3 module, and not all its level 3 replacements are REC yet. Hopefully we'll get there eventually, and as @tabatkins says, even if this isn't done, we're getting closer.

For Level 3 specs, the same logic applies, but since we don't yet have any level 4 REC, we cannot retire any of them just yet either. But in due time, I expect us to. My guess would be that css-cascade may be the first to get there.

[gsnedders]

For CSS2, that means we cannot declare it as superseded just yet, because not all its parts have a Level 3 module, and not all its level 3 replacements are REC yet.

Though we can definitely replace individual sections with references to L3. And in https://github.com/w3c/csswg-drafts/issues/412 we resolved to make syntax informatively defined in L2 by reference to L3.

[gsnedders]

https://github.com/w3c/csswg-drafts/issues/628 and https://github.com/w3c/csswg-drafts/issues/2224 both touch on this with regards specific changes; https://github.com/w3c/csswg-drafts/issues/2936 is also somewhat related.

[fantasai]

Though we can definitely replace individual sections with references to L3.

I think it would be more appropriate to add references to L3, rather than removing sections of 2.

[gsnedders]

Personally, I have little desire to spend my time fixing issues such as #628 in CSS 2 (yet alone checking for other cases where normative behaviour has changed, especially where spec text has been heavily rewritten). I'm not sure how that's a reasonable use of anyone's time?

[tabatkins]

Yeah, I also don't understand what the value is in maintaining sections of CSS2 that have been replaced or impacted by later modules. We should be decreasing our maintenance burden by removing sections as it becomes possible, not increasing it.

@fantasai, can you explain why you think it's valuable to keep those obsolete portions of CSS2 around?

[svgeesus]

This seems like doubling the amount of work for zero benefit.

As I said in define by reference to CSS Color 3 replacing the entire section with a reference is preferable. It is easy to read and understand.

It is better than adding a reference and leaving the original text, because then people assume they should also read and mentally merge the original text and the new reference.

And even that is better than adding a reference and also maintaining a special, subset version of the new reference, which is a huge amount of work and highly error prone.

[gsnedders]

It is better than adding a reference and leaving the original text, because then people assume they should also read and mentally merge the original text and the new reference.

Or, worse, just implement the original text, which is downright harmful.

And even that is better than adding a reference and also maintaining a special, subset version of the new reference, which is a huge amount of work and highly error prone.

FWIW, I think it varies how bad that is. Something like "background-image is defined in Level 3, except that its value is constrained to <bg-image> | inherit in Level 2" is fine.

I don't think the subset approach used in my PR for <color> is bad, FWIW, despite being slightly complex.

[astearns]

Discussed, minutes start here https://logs.csswg.org/irc.w3.org/css/2020-07-30/#e1339466

RESOLVED: sections entirely replaced by RECs are marked with obsoletion notices recommending the REC, but not removed