Supporting levels and level-less drafts in /TR, bikeshed

[Wendy Seltzer]

Hi Spec-Prod,

We've been having discussion whether every spec needs to have a "level"
indicator. I understand that CSS has moved in that direction, even for
"Level 1" drafts, while some other groups have moved to levels only
after v1.

Two data-points:
Mike West reports that bikeshed gives a fatal error when asked to
produce a WD without level metadata.

The pubrules "this version" checker complains about a -1- after a
shortname.

Is there a common view on whether to use levels or not, and if so, how
to indicate them?

Thanks,
--Wendy

[Shane McCarron]

What is the semantic of "Level"?

Post by Wendy Seltzer
Hi Spec-Prod,
We've been having discussion whether every spec needs to have a "level"
indicator. I understand that CSS has moved in that direction, even for
"Level 1" drafts, while some other groups have moved to levels only
after v1.
Mike West reports that bikeshed gives a fatal error when asked to
produce a WD without level metadata.
The pubrules "this version" checker complains about a -1- after a
shortname.
Is there a common view on whether to use levels or not, and if so, how
to indicate them?
Thanks,
--Wendy
--
Policy Counsel and Domain Lead, World Wide Web Consortium (W3C)
https://wendy.seltzer.org/ +1.617.863.0613 (mobile)

[Tab Atkins Jr.]

Post by Wendy Seltzer
We've been having discussion whether every spec needs to have a "level"
indicator. I understand that CSS has moved in that direction, even for
"Level 1" drafts, while some other groups have moved to levels only
after v1.
Mike West reports that bikeshed gives a fatal error when asked to
produce a WD without level metadata.

While I'm going to continue requiring Level metadata, I consider it a
bug that it doesn't handle the semantics of "living" or "currently the
only level" standards well. I'll fix that.

Post by Wendy Seltzer
The pubrules "this version" checker complains about a -1- after a
shortname.

This is a bug in pubrules that's been known for some time (at least a
few years). CSS has been publishing with urls like that for a long
while.

Post by Wendy Seltzer
Is there a common view on whether to use levels or not, and if so, how
to indicate them?

Unless the org has a strong policy on only publishing the spec as a
living standard, I strongly support using CSS's pattern more widely:

1. Every spec is published with a leveled, dated shortname, like
"foo-1-20160425".
2. Additionally, the latest published version of a given level is
available at a leveled shortname, like "foo-1".
3. Additionally, the latest publication of the spec is available at a
plain shortname, like "foo".

W3C in general instead just publishes a dated shortname, and a plain
shortname. This means that, if a second level is ever published, we
either (a) retroactively interpret all links to /TR/foo/ to mean "the
latest level" (and there's no way, prior to this, to validly refer to
just the first level), or (b) interpret /TR/foo/ to always mean the
first level (and so there's no way to just refer to the latest version
of a spec, as you always have to specify a level).

It's not killer, but it's annoying.

Post by Wendy Seltzer
What is the semantic of "Level"?

Within CSS, a "level" is what you'd expect - a new edition of an older
specification.

In Bikeshed, Level is used to implicitly specify that a particular
spec obsoletes another one (with the same shortname and a smaller
level). If you attempt to autolink to a term, and both the obsolete
spec and its superceding version provide refs for that term, the ones
from the obsolete spec are automatically thrown out, so you don't get
any "ambiguous ref" errors.

~TJ

[Marcos Caceres]

Post by Wendy Seltzer
Hi Spec-Prod,
We've been having discussion whether every spec needs to have a "level"
indicator. I understand that CSS has moved in that direction, even for
"Level 1" drafts, while some other groups have moved to levels only
after v1.

I think most people (inside the W3C and outside) don't have any idea what constitutes a "level" vs "edition" vs "version". It just leads to confusion and frustration, because searching for a feature might mean you end up a the wrong "level" or because you don't find the feature at whatever level. I know I've experienced this frustration trying to find CSS stuff (sorry, Tab!)

You don't need to go far to find developers thinking that there is such a thing as a CSS "Version 3"... when is CSS4 coming is a long running joke on twitter (I'm not even sure it's a joke... and I've even seen Tab tweet out in frustration that there is no CSS3).  

I've also been doing standards for about a decade now, and I still have no idea what CSS Levels mean - to an outside-insider, they appear to be completely arbitrary and even more frustrating that versions: does a level obsolete a version? Does it build on it? Can Super Mario jump onto that level or will he reach that level.. because games have levels? is that what levels mean?  

We should just move to living standards and stop with the levels/versions/dates nonsense altogether (as the WHATWG has done): one stable URL is all you need.   

Post by Wendy Seltzer
Is there a common view on whether to use levels or not, and if so, how
to indicate them?

I for one, would be violently against requiring levels for all specs (sorry again, Tab!). I think any kind of versioning is a terrible idea (tho I'm a fan of tagging versions in Git, which is actually useful). 

However, if certain groups want to continue to use them, they should (knowing that they confuse hell out of people like me and people in general). 

[Steve Glaser]

For a non-W3C perspective...

The PCISIG has a concept of Maturity Level. There are defined rules for what must be defined for a given Maturity Level (concepts, mechanisms, exact message and register bit layouts, etc.).

This "level" is orthogonal to the Spec Revision. For example, we're currently working on PCIe Base 4.0 Maturity Level 0.7 (to be followed by 0.9 then 1.0 unless we discover a need to change something that should have been frozen in an earlier maturity level).

My version of Respec will eventually key off Maturity Level and insert the appropriate boilerplate text. It currently just labels every page appropriately.

Steveg

Post by Marcos Caceres

Post by Wendy Seltzer
Hi Spec-Prod,
We've been having discussion whether every spec needs to have a "level"
indicator. I understand that CSS has moved in that direction, even for
"Level 1" drafts, while some other groups have moved to levels only
after v1.

I think most people (inside the W3C and outside) don't have any idea what constitutes a "level" vs "edition" vs "version". It just leads to confusion and frustration, because searching for a feature might mean you end up a the wrong "level" or because you don't find the feature at whatever level. I know I've experienced this frustration trying to find CSS stuff (sorry, Tab!)
You don't need to go far to find developers thinking that there is such a thing as a CSS "Version 3"... when is CSS4 coming is a long running joke on twitter (I'm not even sure it's a joke... and I've even seen Tab tweet out in frustration that there is no CSS3).
I've also been doing standards for about a decade now, and I still have no idea what CSS Levels mean - to an outside-insider, they appear to be completely arbitrary and even more frustrating that versions: does a level obsolete a version? Does it build on it? Can Super Mario jump onto that level or will he reach that level.. because games have levels? is that what levels mean?
We should just move to living standards and stop with the levels/versions/dates nonsense altogether (as the WHATWG has done): one stable URL is all you need.

Post by Wendy Seltzer
Is there a common view on whether to use levels or not, and if so, how
to indicate them?

I for one, would be violently against requiring levels for all specs (sorry again, Tab!). I think any kind of versioning is a terrible idea (tho I'm a fan of tagging versions in Git, which is actually useful).
However, if certain groups want to continue to use them, they should (knowing that they confuse hell out of people like me and people in general).

-----------------------------------------------------------------------------------
This email message is for the sole use of the intended recipient(s) and may contain
confidential information. Any unauthorized review, use, disclosure or distribution
is prohibited. If you are not the intended recipient, please contact the sender by
reply email and destroy all copies of the original message.
-----------------------------------------------------------------------------------

[Tobie Langel]

So looking at some of the comments to the little poll Marcos created[1]
it's blatantly obvious there is no shared understanding whatsoever of
what a level means.

I generally run bikeshed with the -f option because of that.

Overall, we're back to the issue of needing iterative editing on
one side, and having an IP process that's unfit to deal with this on
the other.

Have we considered adopting semver for specs and having major versions
trigger IP commiments in parallel?

--tobie

---
[1]:https://twitter.com/marcosc/status/724808518289776640

[Shane McCarron]

FWIW I have never understood CSS levels. And I don't know how they map to
normal versioning of other things.

As to "living standards" - conformance people don't like living standards
in the same way that they don't like frequent updates of tools. Large
organizations go through a lot of trouble to validate that version X of
something satisfies their requirements. For better or worse, those
organizations represent a big piece of our constituency. In order for
their model to work you need stability.

Post by Tobie Langel
So looking at some of the comments to the little poll Marcos created[1]
it's blatantly obvious there is no shared understanding whatsoever of what
a level means.
I generally run bikeshed with the -f option because of that.
Overall, we're back to the issue of needing iterative editing on one side,
and having an IP process that's unfit to deal with this on the other.
Have we considered adopting semver for specs and having major versions
trigger IP commiments in parallel?
--tobie
---
[1]: https://twitter.com/marcosc/status/724808518289776640

[Tobie Langel]

FWIW I have never understood CSS levels.  And I don't know how they
map to normal versioning of other things.
As to "living standards" - conformance people don't like living
standards in the same way that they don't like frequent updates of
tools.  Large organizations go through a lot of trouble to validate
that version X of something satisfies their requirements.

Living standards don't imply you can't have versions or take snapshots
along the way. They just treat those as by products and not means to
an end. In practice, everyone's looking at editor's drafts anyway, so
living standards is what's happening de facto anyway.

--tobie

[fantasai]

FWIW I have never understood CSS levels. And I don't know how they map to normal versioning of other things.

Levels are the same as versions, except that you can't change anything
in a previous level.

Higher levels are a feature superset of lower levels.

Lower levels might have looser definitions and more undefined functionality
than higher levels.

Basically, it's versioning, adapted to the constraints of the Web.

~fantasai

[Tab Atkins Jr.]

Post by Marcos Caceres

Post by Wendy Seltzer
Hi Spec-Prod,
We've been having discussion whether every spec needs to have a "level"
indicator. I understand that CSS has moved in that direction, even for
"Level 1" drafts, while some other groups have moved to levels only
after v1.

I think most people (inside the W3C and outside) don't have any idea what constitutes a "level" vs "edition" vs "version". It just leads to confusion and frustration, because searching for a feature might mean you end up a the wrong "level" or because you don't find the feature at whatever level. I know I've experienced this frustration trying to find CSS stuff (sorry, Tab!)

level/edition/version are all the same thing. Point is just that *if*
your workmode is to work on a spec for a while, then cut it to a
stable version, and then work on it more, then you're doing levels/etc
and it's good to acknowledge that up-front to avoid future problems
with shortname urls.

The alternate workmode is to do a living standard that just gets
updated as appropriate. That's also 100% fine.

Post by Marcos Caceres
I've also been doing standards for about a decade now, and I still have no idea what CSS Levels mean - to an outside-insider, they appear to be completely arbitrary and even more frustrating that versions: does a level obsolete a version? Does it build on it? Can Super Mario jump onto that level or will he reach that level.. because games have levels? is that what levels mean?

The only confusion I've ever heard from authors is the distinction
between spec levels and "language" levels, caused by the fact that CSS
previously updated all-at-once (and so did HTML, and so does JS).

The concept of levels *themselves* doesn't seem to confuse anyone.

Post by Marcos Caceres
We should just move to living standards and stop with the levels/versions/dates nonsense altogether (as the WHATWG has done): one stable URL is all you need.

That's easy to do with levels *or* living standards - the CSSWG has
for quite a while been ensuring that when we publish "css-foo-3", that
"css-foo" also works and points to the latest thing. Unless you have
a burning need to refer to a specific version, using the unversioned
url is always the easiest and most correct thing to do.

~TJ