Discussion:
Dealing with levels in specs
Tobie Langel
2016-11-16 08:45:25 UTC
Permalink
Hi all,

There's a growing trend in specs right now to start releasing different
levels of a same spec. It seems it's mainly done to comply with Rec
track requirements without slowing down editing too much.

I'd have plenty to say on the irony of editing different spec levels for
evergreen browsers. And I still don't understand why we're not taking
advantage of versioning to fast-track spec snapshots to secure IPR at
regular intervals instead (which would avoid sidetracking the whole
editing process). But I guess that's a conversation for another time.

So going back to spec levels, it seems there's no structure in place
within W3C to handle these levels correctly. From my conversations with
Denis, it seems W3C treats each level as a different independent entity
and then does some ad-hoc redirecting on /TR/ depending on requests from
editors or chairs.

This leads to absurd situations such as that of the Service Workers
spec. Currently, we'll find:

An October 11 WD at https://www.w3.org/TR/service-workers-1/ which point
to a "Service Workers 1" ED at https://w3c.github.io/ServiceWorker/v1/.

A June 25, 2015 WD on https://www.w3.org/TR/service-workers/ which is
obviously very much outdated and points to an ED at
https://slightlyoff.github.io/ServiceWorker/spec/service_worker/ which
itself redirects to a "Service Workers Nightly" ED at
https://w3c.github.io/ServiceWorker/ (which according to the editors is
the one which should be referenced).

W3C's API (which Specref pulls data from hourly) makes no mention of the
latter, and thus everyone is incorrectly directed to the former (with
it's level-1 ED implementors should *not* be tracking).

I've bumped into similar issues with CSP which I had to manually fix in
Specref and others before that.

If W3C wants to go down the leveled-spec road instead of fixing its IPR
process, it needs to do so in a structured and organized way:

- Automate where /tr/shortname/ points so there's consistency across
specs.
- Document this so all WGs are consistent.
- Tie all levels together and not consider them as disjoint specs.
- Make sure the model you implement works with Specref so it can be
properly integrated.
- Enforce one ED referenced per shortname (in pubrules).

I know Denis has started working on some of this. I'm essentially
writing this email to suggest this issues get discussed in the open and
the work to fix it gets prioritized.

Thanks for your time,

--tobie
Philippe Le Hégaret
2016-11-16 12:48:07 UTC
Permalink
Post by Tobie Langel
There's a growing trend in specs right now to start releasing different
levels of a same spec. It seems it's mainly done to comply with Rec
track requirements without slowing down editing too much.
I'd have plenty to say on the irony of editing different spec levels for
evergreen browsers. And I still don't understand why we're not taking
advantage of versioning to fast-track spec snapshots to secure IPR at
regular intervals instead (which would avoid sidetracking the whole
editing process). But I guess that's a conversation for another time.
That's the approach a few Groups like webperf and webappsec adopted a
while ago. We didn't spread the practice yet across all groups.
Post by Tobie Langel
So going back to spec levels, it seems there's no structure in place
within W3C to handle these levels correctly. From my conversations with
Denis, it seems W3C treats each level as a different independent entity
and then does some ad-hoc redirecting on /TR/ depending on requests from
editors or chairs.
That's correct.
Post by Tobie Langel
This leads to absurd situations such as that of the Service Workers
An October 11 WD at https://www.w3.org/TR/service-workers-1/ which point
to a "Service Workers 1" ED at https://w3c.github.io/ServiceWorker/v1/.
A June 25, 2015 WD on https://www.w3.org/TR/service-workers/ which is
obviously very much outdated and points to an ED at
https://slightlyoff.github.io/ServiceWorker/spec/service_worker/ which
itself redirects to a "Service Workers Nightly" ED at
https://w3c.github.io/ServiceWorker/ (which according to the editors is
the one which should be referenced).
W3C's API (which Specref pulls data from hourly) makes no mention of the
latter, and thus everyone is incorrectly directed to the former (with
it's level-1 ED implementors should *not* be tracking).
I've bumped into similar issues with CSP which I had to manually fix in
Specref and others before that.
... you missed webperf. We're in a similar situation with this as well,
mainly due to lack of tooling support.
Post by Tobie Langel
If W3C wants to go down the leveled-spec road instead of fixing its IPR
- Automate where /tr/shortname/ points so there's consistency across
specs.
- Document this so all WGs are consistent.
- Tie all levels together and not consider them as disjoint specs.
- Make sure the model you implement works with Specref so it can be
properly integrated.
- Enforce one ED referenced per shortname (in pubrules).
Whatever model we adopt, we also need respec and bikeshed to adopt them
as well. They don't have builtin support for multiple latest versions.
Post by Tobie Langel
I know Denis has started working on some of this. I'm essentially
writing this email to suggest this issues get discussed in the open and
the work to fix it gets prioritized.
Indeed, Denis is looking into it and tasked to provide a proposal to
spec-prod by early 2017 at the latest. It's at the top of his list. Goal
is to get the final proposal adopted no later than the AC meeting in
April 2017 (we don't need AC approval for this, it's just a deadline in
my mind). Note that, as part of this, he is also looking at revamping
our approach to the /TR page itself. In its present state, it's not
helpful (some would easily say, quite the contrary in fact). We don't
have a solution for SEOs yet unfortunately but I'd like to fix that one
sooner rather than later as well.

Philippe
Tobie Langel
2016-11-16 13:41:40 UTC
Permalink
Post by Philippe Le Hégaret
Post by Tobie Langel
I'd have plenty to say on the irony of editing different spec levels for
evergreen browsers. And I still don't understand why we're not taking
advantage of versioning to fast-track spec snapshots to secure IPR at
regular intervals instead (which would avoid sidetracking the whole
editing process). But I guess that's a conversation for another time.
That's the approach a few Groups like webperf and webappsec adopted a
while ago. We didn't spread the practice yet across all groups.
Well it seems specs in these groups still have levels, so I'm slightly
confused as to how that's supposed to work.
Post by Philippe Le Hégaret
Post by Tobie Langel
If W3C wants to go down the leveled-spec road instead of fixing its IPR
- Automate where /tr/shortname/ points so there's consistency across
specs.
- Document this so all WGs are consistent.
- Tie all levels together and not consider them as disjoint specs.
- Make sure the model you implement works with Specref so it can be
properly integrated.
- Enforce one ED referenced per shortname (in pubrules).
Whatever model we adopt, we also need respec and bikeshed to adopt them
as well. They don't have builtin support for multiple latest versions.
I'm not sure how that would work precisely practice, but "polyfilling"
that in both specs using custom metadata fields seems trivial.

It's the process/policy aspect that seems more tedious to setup at
present.
Post by Philippe Le Hégaret
Post by Tobie Langel
I know Denis has started working on some of this. I'm essentially
writing this email to suggest this issues get discussed in the open and
the work to fix it gets prioritized.
Indeed, Denis is looking into it and tasked to provide a proposal to
spec-prod by early 2017 at the latest. It's at the top of his list.
OK that's great news.
Post by Philippe Le Hégaret
Goal is to get the final proposal adopted no later than the AC meeting in
April 2017 (we don't need AC approval for this, it's just a deadline in
my mind). Note that, as part of this, he is also looking at revamping
our approach to the /TR page itself.
I'm not sure I see the value in having both of these things tied
together.

/tr has been a train-wreck since forever. Fixing it is good, but
everyone's used to its current state at present. It's not really a
blocker.

On the other hand, the level-related mess is becoming more painful by
the day. It impacts spec publishing (incorrect URLs), implementors
working on outdated content, authors not reading the right specs, etc.

The faster this is fixed, the better.

--tobie
Philippe Le Hégaret
2016-11-16 18:27:46 UTC
Permalink
Post by Tobie Langel
Post by Philippe Le Hégaret
Whatever model we adopt, we also need respec and bikeshed to adopt them
as well. They don't have builtin support for multiple latest versions.
I'm not sure how that would work precisely practice, but "polyfilling"
that in both specs using custom metadata fields seems trivial.
It's the process/policy aspect that seems more tedious to setup at
present.
Agreed. We need to sort out the process/policy first.
Post by Tobie Langel
Post by Philippe Le Hégaret
Goal is to get the final proposal adopted no later than the AC meeting in
April 2017 (we don't need AC approval for this, it's just a deadline in
my mind). Note that, as part of this, he is also looking at revamping
our approach to the /TR page itself.
I'm not sure I see the value in having both of these things tied
together.
In my mind, if we're going to revamp our latest version links, we should
make sure that what we'll end up with something that can be coherent on /TR.
Post by Tobie Langel
/tr has been a train-wreck since forever. Fixing it is good, but
everyone's used to its current state at present. It's not really a
blocker.
It's certainly certainly not a blocker on agreeing on latest version
links process/policy and getting our specs to adopt it.
Post by Tobie Langel
On the other hand, the level-related mess is becoming more painful by
the day. It impacts spec publishing (incorrect URLs), implementors
working on outdated content, authors not reading the right specs, etc.
The faster this is fixed, the better.
+1

Philippe
Liam R. E. Quin
2016-11-16 18:14:19 UTC
Permalink
Post by Tobie Langel
There's a growing trend in specs right now to start releasing
different
levels of a same spec. It seems it's mainly done to comply with Rec
track requirements without slowing down editing too much.
Note that in addition to levels there are also editions - e.g. CSS 2.1
2nd edition to correct errata.

In theory there could be a 2nd edition of (say) CSS level 2 text.
Post by Tobie Langel
So going back to spec levels, it seems there's no structure in place
within W3C to handle these levels correctly.
Nor is there consistent use of teminology across Working Groups.

Nor do we have a requirement that Working Groups provide a mechanism to
identify to which levels and editions of which specs they are trying to
conform, making validation and archiving difficult.
Post by Tobie Langel
[...]
If W3C wants to go down the leveled-spec road instead of fixing its
IPR process
When the method of working is at odds with the IPR legal framework we
have to ask which is broken and how. The way that specs are being
edited, as you rightly point out, has descended into chaos. Part of
that was because new tooling such as respec and github came along that
were so much easier than using CVS and edln :), that people editing
specs rebelled individually.

Probably we need to rein that in a bit.
Post by Tobie Langel
- Automate where /tr/shortname/ points so there's consistency across
specs.
Note, this would need to be done for all the existing specs too, I
presume.
Post by Tobie Langel
- Document this so all WGs are consistent.
- Tie all levels together and not consider them as disjoint specs.
- Make sure the model you implement works with Specref so it can be
properly integrated.
OK...
Post by Tobie Langel
- Enforce one ED referenced per shortname (in pubrules).
so no branches?

You raise good points, I'm glad you've started a discussion here.

Liam
Tobie Langel
2016-11-17 14:08:46 UTC
Permalink
Post by Liam R. E. Quin
Post by Tobie Langel
There's a growing trend in specs right now to start releasing different
levels of a same spec. It seems it's mainly done to comply with Rec
track requirements without slowing down editing too much.
Note that in addition to levels there are also editions - e.g. CSS 2.1
2nd edition to correct errata.
Like most things, there's a tradeoff. Or we keep the system simple
enough that is economically sound to build tools to make our lives
easier or we don;t and we're back to manual work.
Post by Liam R. E. Quin
In theory there could be a 2nd edition of (say) CSS level 2 text.
Well, if you consider all of these things a mere tags or branches,
then's that's fine I suppose.
Post by Liam R. E. Quin
Post by Tobie Langel
So going back to spec levels, it seems there's no structure in place
within W3C to handle these levels correctly.
Nor is there consistent use of teminology across Working Groups.
There's no centralized place where that terminology is defined, so no
wonder.
Post by Liam R. E. Quin
Nor do we have a requirement that Working Groups provide a mechanism to
identify to which levels and editions of which specs they are trying to
conform, making validation and archiving difficult.
Specref provides that when it can. So it's available to spec editors
using Bikeshed or Respec.
Post by Liam R. E. Quin
Post by Tobie Langel
If W3C wants to go down the leveled-spec road instead of fixing its
IPR process
When the method of working is at odds with the IPR legal framework we
have to ask which is broken and how. The way that specs are being
edited, as you rightly point out, has descended into chaos. Part of
that was because new tooling such as respec and github came along that
were so much easier than using CVS and edln :), that people editing
specs rebelled individually.
Probably we need to rein that in a bit.
People end up using the tools that makes their job easier. When one
wants to reign things in, it's easy, do it as part of improving people's
workflow.

For example, simplify the steps to obtain a shortname for new specs that
abide by whatever model is agreed upon (i.e. don't need director
approval for it).
Post by Liam R. E. Quin
Post by Tobie Langel
- Automate where /tr/shortname/ points so there's consistency across
specs.
Note, this would need to be done for all the existing specs too, I
presume.
Yes.
Post by Liam R. E. Quin
Post by Tobie Langel
- Document this so all WGs are consistent.
- Tie all levels together and not consider them as disjoint specs.
- Make sure the model you implement works with Specref so it can be
properly integrated.
OK...
The model I have in mind is that the shortname is roughly equivalent to
a Git repository. The levels, Rec track statuses, etc. are just
branches. The ED is the tip of the master branch. There might be some
things to figure out more precisely, but roughly, that's the idea.
Post by Liam R. E. Quin
Post by Tobie Langel
- Enforce one ED referenced per shortname (in pubrules).
so no branches?
Branches are fine, drafts per level are fine. What's required however is
a way to identify the tip of the master branch (and call it the ED).

--tobie
Tab Atkins Jr.
2016-11-19 00:07:58 UTC
Permalink
Post by Tobie Langel
Post by Liam R. E. Quin
Post by Tobie Langel
There's a growing trend in specs right now to start releasing different
levels of a same spec. It seems it's mainly done to comply with Rec
track requirements without slowing down editing too much.
Note that in addition to levels there are also editions - e.g. CSS 2.1
2nd edition to correct errata.
Like most things, there's a tradeoff. Or we keep the system simple
enough that is economically sound to build tools to make our lives
easier or we don;t and we're back to manual work.
Post by Liam R. E. Quin
In theory there could be a 2nd edition of (say) CSS level 2 text.
Well, if you consider all of these things a mere tags or branches,
then's that's fine I suppose.
I'm not sure why the CSSWG chose to do CSS2.1 2nd edition instead of
just publishing CSS 2.2; we're *now* publishing 2.2 and it's fine. It
would be great to just rule that out, and mandate that specs can only
have one level. We'll never do multiple "editions" of any post-CSS2
modules; we'll just publish another level.
Post by Tobie Langel
Post by Liam R. E. Quin
Nor do we have a requirement that Working Groups provide a mechanism to
identify to which levels and editions of which specs they are trying to
conform, making validation and archiving difficult.
Specref provides that when it can. So it's available to spec editors
using Bikeshed or Respec.
Referring to specific versions of a standard is a strong anti-pattern;
the web isn't made out of standards, it's made out of browsers, and
whatever version they implement is the one that specs should be
authored against (and, when necessary, updated to conform to).
Post by Tobie Langel
Post by Liam R. E. Quin
Post by Tobie Langel
If W3C wants to go down the leveled-spec road instead of fixing its
IPR process
When the method of working is at odds with the IPR legal framework we
have to ask which is broken and how. The way that specs are being
edited, as you rightly point out, has descended into chaos. Part of
that was because new tooling such as respec and github came along that
were so much easier than using CVS and edln :), that people editing
specs rebelled individually.
Probably we need to rein that in a bit.
I don't understand how the tools had anything to do with this. Git vs
CVS has no bearing on whether/how people use levels (or don't).
Editing tools don't either. This is about publishing practices.
Post by Tobie Langel
People end up using the tools that makes their job easier. When one
wants to reign things in, it's easy, do it as part of improving people's
workflow.
For example, simplify the steps to obtain a shortname for new specs that
abide by whatever model is agreed upon (i.e. don't need director
approval for it).
Is that one of the issues we're actually running into?
Post by Tobie Langel
Post by Liam R. E. Quin
Post by Tobie Langel
- Automate where /tr/shortname/ points so there's consistency across
specs.
Note, this would need to be done for all the existing specs too, I
presume.
Yes.
Post by Liam R. E. Quin
Post by Tobie Langel
- Document this so all WGs are consistent.
- Tie all levels together and not consider them as disjoint specs.
- Make sure the model you implement works with Specref so it can be
properly integrated.
OK...
The model I have in mind is that the shortname is roughly equivalent to
a Git repository. The levels, Rec track statuses, etc. are just
branches. The ED is the tip of the master branch. There might be some
things to figure out more precisely, but roughly, that's the idea.
Post by Liam R. E. Quin
Post by Tobie Langel
- Enforce one ED referenced per shortname (in pubrules).
so no branches?
Branches are fine, drafts per level are fine. What's required however is
a way to identify the tip of the master branch (and call it the ED).
Yes. CSSWG *does* carry EDs for every individual level, as well, but
for previous levels these shouldn't diverge from the TR version except
for short periods when you're preparing to backport a change from a
later level. I wouldn't be sad if we adopted a policy that disallowed
this; at worst, we just maintain the old version separately, nothing
links directly to it, and all the drafts point to the "latest" ED (via
a well-known URL).

Like, my personal preference would be URL structures that are
automatically shaped like:

/TR/foo-1 <= the level 1 of the foo spec
/TR/foo-2 <= the level 2 of the foo spec
/TR/foo <= the ED of the foo spec

Or, if we wanted to enforce a little more separation between legal-TR
and ED, this would also work:

/TR/foo-1 <= level 1
/TR/foo-2 <= level 2
/TR/foo <= level 2 right now, shifts if level 3 gets published
/TR/foo/latest <= ED, or with some similar sort of URL pattern

Right now the CSSWG manually requests the latter structure when we
publish (and some things are inconsistent as a result), except our EDs
are on a different server altogether.

~TJ
Tobie Langel
2016-11-19 13:59:25 UTC
Permalink
Post by Tab Atkins Jr.
Post by Tobie Langel
Post by Liam R. E. Quin
Note that in addition to levels there are also editions - e.g. CSS 2.1
2nd edition to correct errata.
Like most things, there's a tradeoff. Or we keep the system simple
enough that is economically sound to build tools to make our lives
easier or we don;t and we're back to manual work.
Post by Liam R. E. Quin
In theory there could be a 2nd edition of (say) CSS level 2 text.
Well, if you consider all of these things a mere tags or branches,
then's that's fine I suppose.
I'm not sure why the CSSWG chose to do CSS2.1 2nd edition instead of
just publishing CSS 2.2; we're *now* publishing 2.2 and it's fine. It
would be great to just rule that out, and mandate that specs can only
have one level. We'll never do multiple "editions" of any post-CSS2
modules; we'll just publish another level.
Yes please.
Post by Tab Atkins Jr.
Post by Tobie Langel
Post by Liam R. E. Quin
Nor do we have a requirement that Working Groups provide a mechanism to
identify to which levels and editions of which specs they are trying to
conform, making validation and archiving difficult.
Specref provides that when it can. So it's available to spec editors
using Bikeshed or Respec.
Referring to specific versions of a standard is a strong anti-pattern;
the web isn't made out of standards, it's made out of browsers, and
whatever version they implement is the one that specs should be
authored against (and, when necessary, updated to conform to).
Yes, I agree. There are some (uncommon) use cases for referencing
specific spec versions, though. Especially in a non-normative context
(e.g. this was included in the [[XXX]] spec up to [[XXX-YYYYMMDD]] but
it now in its own document: [[[YYY]]]).
Post by Tab Atkins Jr.
Post by Tobie Langel
Post by Liam R. E. Quin
Post by Tobie Langel
If W3C wants to go down the leveled-spec road instead of fixing its
IPR process
When the method of working is at odds with the IPR legal framework we
have to ask which is broken and how. The way that specs are being
edited, as you rightly point out, has descended into chaos. Part of
that was because new tooling such as respec and github came along that
were so much easier than using CVS and edln :), that people editing
specs rebelled individually.
Probably we need to rein that in a bit.
I don't understand how the tools had anything to do with this. Git vs
CVS has no bearing on whether/how people use levels (or don't).
Editing tools don't either. This is about publishing practices.
Bikeshed balking on the absence of levels is de facto enforcing their
usage.
Post by Tab Atkins Jr.
Post by Tobie Langel
People end up using the tools that makes their job easier. When one
wants to reign things in, it's easy, do it as part of improving people's
workflow.
For example, simplify the steps to obtain a shortname for new specs that
abide by whatever model is agreed upon (i.e. don't need director
approval for it).
Is that one of the issues we're actually running into?
It was a contrived example to suggest fixing problems by improving
editors life rather than enforcing rules.
Post by Tab Atkins Jr.
Post by Tobie Langel
Post by Liam R. E. Quin
Post by Tobie Langel
- Enforce one ED referenced per shortname (in pubrules).
so no branches?
Branches are fine, drafts per level are fine. What's required however is
a way to identify the tip of the master branch (and call it the ED).
Yes. CSSWG *does* carry EDs for every individual level, as well, but
for previous levels these shouldn't diverge from the TR version except
for short periods when you're preparing to backport a change from a
later level. I wouldn't be sad if we adopted a policy that disallowed
this; at worst, we just maintain the old version separately, nothing
links directly to it, and all the drafts point to the "latest" ED (via
a well-known URL).
Older levels could have a link to both the current shortname ED and
eventually a level-ED (marked differently), so it's clear what the up do
date ED is.

Your below proposal (which has a /tr link that consistently hosts or
redirect to the ED solves the same problem).
Post by Tab Atkins Jr.
Like, my personal preference would be URL structures that are
/TR/foo-1 <= the level 1 of the foo spec
/TR/foo-2 <= the level 2 of the foo spec
/TR/foo <= the ED of the foo spec
YES.
Post by Tab Atkins Jr.
Or, if we wanted to enforce a little more separation between legal-TR
/TR/foo-1 <= level 1
/TR/foo-2 <= level 2
/TR/foo <= level 2 right now, shifts if level 3 gets published
When to shift is actually contentious. E.g. some folks will prefer
/TR/foo point to Level 3 FPWD, others to Level 2 CR, yet others to Level
1 REC. Not that I really care, but just pointing out it' a conversation
that will need to happen.
Post by Tab Atkins Jr.
/TR/foo/latest <= ED, or with some similar sort of URL pattern
Right now the CSSWG manually requests the latter structure when we
publish (and some things are inconsistent as a result), except our EDs
are on a different server altogether.
/TR/foo/latest --301--> ED

would work for me in that case.

--tobie
Liam R. E. Quin
2016-11-19 21:39:55 UTC
Permalink
Post by Tab Atkins Jr.
Post by Tobie Langel
Post by Liam R. E. Quin
In theory there could be a 2nd edition of (say) CSS level 2 text.
Well, if you consider all of these things a mere tags or branches,
then's that's fine I suppose.
I'm not sure why the CSSWG chose to do CSS2.1 2nd edition instead of
just publishing CSS 2.2; we're *now* publishing 2.2 and it's
fine.  It would be great to just rule that out, and mandate that
specs can only have one level.
It's a question of whether we have to deal with what is and what has
been or only what we hope to be. I'm not the one doing the work :-) so
just wanted to point out that the assumption didn't quite hold.
Post by Tab Atkins Jr.
  We'll never do multiple "editions" of any post-CSS2
modules; we'll just publish another level.
Other WGs use editions and versions and not levels. So both models are
in use.

[...]
Post by Tab Atkins Jr.
Post by Tobie Langel
For example, simplify the steps to obtain a shortname for new specs that
abide by whatever model is agreed upon (i.e. don't need director
approval for it).
Is that one of the issues we're actually running into?
It can cause a delay in some cases today.
[...]
Post by Tab Atkins Jr.
Like, my personal preference would be URL structures that are
/TR/foo-1 <= the level 1 of the foo spec
/TR/foo-2 <= the level 2 of the foo spec
/TR/foo   <= the ED of the foo spec
Or, if we wanted to enforce a little more separation between legal-TR
/TR/foo-1 <= level 1
/TR/foo-2 <= level 2
/TR/foo   <= level 2 right now, shifts if level 3 gets published
/TR/foo/latest <= ED, or with some similar sort of URL pattern
Currently I think the idea is for /TR/foo to go to a Wikipedia
Disambiguation Page :) listing the versions. Certainly I wouldn't want
(say) www.w3.org/TR/xml to go to an editor's draft, since XML is
stable. Same with XQuery or XPath. Going to the latest Rec seems fine
too. Different people want different things from /TR though, and
different WGs and specs work in different ways. I'm fine with Tab's
approach for CSS but not fine with it for some other groups.

Liam
Tab Atkins Jr.
2016-11-21 23:42:47 UTC
Permalink
Post by Liam R. E. Quin
Post by Tab Atkins Jr.
We'll never do multiple "editions" of any post-CSS2
modules; we'll just publish another level.
Other WGs use editions and versions and not levels. So both models are
in use.
They're all the same thing, tho, so we (the W3C) can just settle on
one definitive model and encode it in our URL structure.
Straightforward increasing integers are simple and easy to work with
for both humans and machines.
Post by Liam R. E. Quin
[...]
Post by Tab Atkins Jr.
Post by Tobie Langel
For example, simplify the steps to obtain a shortname for new specs that
abide by whatever model is agreed upon (i.e. don't need director
approval for it).
Is that one of the issues we're actually running into?
It can cause a delay in some cases today.
[...]
Post by Tab Atkins Jr.
Like, my personal preference would be URL structures that are
/TR/foo-1 <= the level 1 of the foo spec
/TR/foo-2 <= the level 2 of the foo spec
/TR/foo <= the ED of the foo spec
Or, if we wanted to enforce a little more separation between legal-TR
/TR/foo-1 <= level 1
/TR/foo-2 <= level 2
/TR/foo <= level 2 right now, shifts if level 3 gets published
/TR/foo/latest <= ED, or with some similar sort of URL pattern
Currently I think the idea is for /TR/foo to go to a Wikipedia
Disambiguation Page :) listing the versions. Certainly I wouldn't want
(say) www.w3.org/TR/xml to go to an editor's draft, since XML is
stable. Same with XQuery or XPath. Going to the latest Rec seems fine
too. Different people want different things from /TR though, and
different WGs and specs work in different ways. I'm fine with Tab's
approach for CSS but not fine with it for some other groups.
The whole point of this exercise is getting to a consistent future for
*all* the groups. It kinda defeats the purpose to have one URL
structure for CSS and different ones for other WGs. ^_^

I'm okay with /TR/foo going to a disambiguation page, at minimum
pointing to the latest published TR-level document and the ED.
That'll probably break some links in CSS specs, but our EDs get
auto-built, and we can mass-republish our TR-level stuff. Then
/TR/foo-1, etc can go to the TR-level documents, and /TR/foo-latest
can go to the ED.

~TJ
Tobie Langel
2016-11-21 23:47:09 UTC
Permalink
Post by Tab Atkins Jr.
Post by Liam R. E. Quin
Currently I think the idea is for /TR/foo to go to a Wikipedia
Disambiguation Page :) listing the versions. Certainly I wouldn't want
(say) www.w3.org/TR/xml to go to an editor's draft, since XML is
stable. Same with XQuery or XPath. Going to the latest Rec seems fine
too. Different people want different things from /TR though, and
different WGs and specs work in different ways. I'm fine with Tab's
approach for CSS but not fine with it for some other groups.
The whole point of this exercise is getting to a consistent future for
*all* the groups. It kinda defeats the purpose to have one URL
structure for CSS and different ones for other WGs. ^_^
I'm okay with /TR/foo going to a disambiguation page, at minimum
pointing to the latest published TR-level document and the ED.
That'll probably break some links in CSS specs, but our EDs get
auto-built, and we can mass-republish our TR-level stuff. Then
/TR/foo-1, etc can go to the TR-level documents, and /TR/foo-latest
can go to the ED.
Couldn't agree more. I accidentally emailed Liam only when replying
earlier but said as much: The lack of consistency has been W3C's biggest
hurdle. It would be nice to solve that.

--tobie
fantasai
2016-11-24 06:18:02 UTC
Permalink
Post by Tab Atkins Jr.
Like, my personal preference would be URL structures that are
/TR/foo-1 <= the level 1 of the foo spec
/TR/foo-2 <= the level 2 of the foo spec
/TR/foo <= the ED of the foo spec
Or, if we wanted to enforce a little more separation between legal-TR
/TR/foo-1 <= level 1
/TR/foo-2 <= level 2
/TR/foo <= level 2 right now, shifts if level 3 gets published
/TR/foo/latest <= ED, or with some similar sort of URL pattern
Right now the CSSWG manually requests the latter structure when we
publish (and some things are inconsistent as a result), except our EDs
are on a different server altogether.
I'd like to close the gap on ED->TR such that there is no need for anyone
other than the editor and the people reviewing the editor's latest set of
changes for correctness to look at the ED. We've made a lot of progress
towards that this year by having automated publishing for WDs. CSSWG
still needs to push updates to many of its drafts, and then set them up
for push-button publishing so that they can stay up-to-date, with changes
pushed to /TR immediately after the corresponding WG resolution. But once
that happens, it should no longer be necessary for most people to reference
the EDs.

As for what to do with EDs, I'd like to have an ED for each thing that's
published on /TR so that when I need to make a set of changes to any one
of them, I can point people to a public URL for said review. :) It's not
good enough to have one ED for multiple levels, as they are different
documents, and we frequently have more than one level actively maintained
at any given point. (E.g. one level is CR, and accepting fixes based on
implementation feedback, while one level is WD and churning as we design
new features.)

So my preferred URL structure would be like the first one:

/TR/foo-1 <-- level 1 functionality, most up-to-date copy that anyone
other than my co-contributors should be looking at
/TR/foo-2 <-- level 2 functionality, most up-to-date copy that anyone
other than my co-contributors should be looking at
/TR/foo <-- internal redirect to whatever level WG considers "stable"
or alternately a disambiguation page

EDs could be hosted on a separate server or mirrored on /TR or given
/TR/foo-1/ed redirects/proxies/whatever--I don't particularly care.
Their purpose is to be a publicly shared copy of whatever I'm currently
working on in whatever state of order or disarray it happens to be, and
only people who are helping me with currently-tasked edits should need
to know where they are.

~fantasai
Denis Ah-Kang
2016-12-16 12:06:23 UTC
Permalink
Hi all,

Thanks Tobie for starting the thread of that topic. Levels on /TR have
indeed started to cause of a lot of problems because so far, we
don't have a good way to manage the different versions of a
specification.
After discussing with different people, we came up with a document
listing 3 proposals aiming at normalizing the latest version links. It
is available at:
https://w3c.github.io/tr-links/versioning/

The idea is to introduce new links to help the different
audiences (browser implementors, web developers, etc) find the
version of the specification they are looking for.

Please take a look at the document and I encourage you to create
issues on the Github repository [1] if you have any questions/comments.
FYI, I created an issue for each proposal [2][3][4]. Feel free to
comment on it and/or +1 on your preferred proposal.

Thank you,

Denis

[1] https://github.com/w3c/tr-links
[2] https://github.com/w3c/tr-links/issues/1
[3] https://github.com/w3c/tr-links/issues/2
[4] https://github.com/w3c/tr-links/issues/3
Post by Tobie Langel
Hi all,
There's a growing trend in specs right now to start releasing different
levels of a same spec. It seems it's mainly done to comply with Rec
track requirements without slowing down editing too much.
I'd have plenty to say on the irony of editing different spec levels for
evergreen browsers. And I still don't understand why we're not taking
advantage of versioning to fast-track spec snapshots to secure IPR at
regular intervals instead (which would avoid sidetracking the whole
editing process). But I guess that's a conversation for another time.
So going back to spec levels, it seems there's no structure in place
within W3C to handle these levels correctly. From my conversations with
Denis, it seems W3C treats each level as a different independent entity
and then does some ad-hoc redirecting on /TR/ depending on requests from
editors or chairs.
This leads to absurd situations such as that of the Service Workers
An October 11 WD at https://www.w3.org/TR/service-workers-1/ which point
to a "Service Workers 1" ED at https://w3c.github.io/ServiceWorker/v1/.
A June 25, 2015 WD on https://www.w3.org/TR/service-workers/ which is
obviously very much outdated and points to an ED at
https://slightlyoff.github.io/ServiceWorker/spec/service_worker/ which
itself redirects to a "Service Workers Nightly" ED at
https://w3c.github.io/ServiceWorker/ (which according to the editors is
the one which should be referenced).
W3C's API (which Specref pulls data from hourly) makes no mention of the
latter, and thus everyone is incorrectly directed to the former (with
it's level-1 ED implementors should *not* be tracking).
I've bumped into similar issues with CSP which I had to manually fix in
Specref and others before that.
If W3C wants to go down the leveled-spec road instead of fixing its IPR
- Automate where /tr/shortname/ points so there's consistency across
specs.
- Document this so all WGs are consistent.
- Tie all levels together and not consider them as disjoint specs.
- Make sure the model you implement works with Specref so it can be
properly integrated.
- Enforce one ED referenced per shortname (in pubrules).
I know Denis has started working on some of this. I'm essentially
writing this email to suggest this issues get discussed in the open and
the work to fix it gets prioritized.
Thanks for your time,
--tobie
Tobie Langel
2016-12-16 16:47:39 UTC
Permalink
Thanks for writing this up.

The main issue I have so far is the terms you use aren't defined clearly
enough.

What does: "latest stable version" mean? WD? REC?
What does "latest version under development" mean? WD? ED?

More importantly, how do you handle common cases where you have:

level-1 is REC
level-2 is CR
level-3 is WD

What's stable above?

What about:

level-1 is CR
level-2 is ED

There is no level-2 WD so far, but ED is being used and referenced by
everyone. What's stable, what's under development?

Have you considered looking at this in different terms instead: eg
what's ready for IPR commitment and what isn't?

--tobie
Post by Tobie Langel
Hi all,
Thanks Tobie for starting the thread of that topic. Levels on /TR have
indeed started to cause of a lot of problems because so far, we
don't have a good way to manage the different versions of a
specification.
After discussing with different people, we came up with a document
listing 3 proposals aiming at normalizing the latest version links. It
https://w3c.github.io/tr-links/versioning/
The idea is to introduce new links to help the different
audiences (browser implementors, web developers, etc) find the
version of the specification they are looking for.
Please take a look at the document and I encourage you to create
issues on the Github repository [1] if you have any questions/comments.
FYI, I created an issue for each proposal [2][3][4]. Feel free to
comment on it and/or +1 on your preferred proposal.
Thank you,
Denis
[1] https://github.com/w3c/tr-links
[2] https://github.com/w3c/tr-links/issues/1
[3] https://github.com/w3c/tr-links/issues/2
[4] https://github.com/w3c/tr-links/issues/3
Post by Tobie Langel
Hi all,
There's a growing trend in specs right now to start releasing different
levels of a same spec. It seems it's mainly done to comply with Rec
track requirements without slowing down editing too much.
I'd have plenty to say on the irony of editing different spec levels for
evergreen browsers. And I still don't understand why we're not taking
advantage of versioning to fast-track spec snapshots to secure IPR at
regular intervals instead (which would avoid sidetracking the whole
editing process). But I guess that's a conversation for another time.
So going back to spec levels, it seems there's no structure in place
within W3C to handle these levels correctly. From my conversations with
Denis, it seems W3C treats each level as a different independent entity
and then does some ad-hoc redirecting on /TR/ depending on requests from
editors or chairs.
This leads to absurd situations such as that of the Service Workers
An October 11 WD at https://www.w3.org/TR/service-workers-1/ which point
to a "Service Workers 1" ED at https://w3c.github.io/ServiceWorker/v1/.
A June 25, 2015 WD on https://www.w3.org/TR/service-workers/ which is
obviously very much outdated and points to an ED at
https://slightlyoff.github.io/ServiceWorker/spec/service_worker/ which
itself redirects to a "Service Workers Nightly" ED at
https://w3c.github.io/ServiceWorker/ (which according to the editors is
the one which should be referenced).
W3C's API (which Specref pulls data from hourly) makes no mention of the
latter, and thus everyone is incorrectly directed to the former (with
it's level-1 ED implementors should *not* be tracking).
I've bumped into similar issues with CSP which I had to manually fix in
Specref and others before that.
If W3C wants to go down the leveled-spec road instead of fixing its IPR
- Automate where /tr/shortname/ points so there's consistency across
specs.
- Document this so all WGs are consistent.
- Tie all levels together and not consider them as disjoint specs.
- Make sure the model you implement works with Specref so it can be
properly integrated.
- Enforce one ED referenced per shortname (in pubrules).
I know Denis has started working on some of this. I'm essentially
writing this email to suggest this issues get discussed in the open and
the work to fix it gets prioritized.
Thanks for your time,
--tobie
Tab Atkins Jr.
2016-12-16 20:45:14 UTC
Permalink
Post by Tobie Langel
Hi all,
Thanks Tobie for starting the thread of that topic. Levels on /TR have
indeed started to cause of a lot of problems because so far, we
don't have a good way to manage the different versions of a
specification.
After discussing with different people, we came up with a document
listing 3 proposals aiming at normalizing the latest version links. It
https://w3c.github.io/tr-links/versioning/
The idea is to introduce new links to help the different
audiences (browser implementors, web developers, etc) find the
version of the specification they are looking for.
Please take a look at the document and I encourage you to create
issues on the Github repository [1] if you have any questions/comments.
FYI, I created an issue for each proposal [2][3][4]. Feel free to
comment on it and/or +1 on your preferred proposal.
Thank you,
Denis
[1] https://github.com/w3c/tr-links
[2] https://github.com/w3c/tr-links/issues/1
[3] https://github.com/w3c/tr-links/issues/2
[4] https://github.com/w3c/tr-links/issues/3
I like this overall, thanks so much for putting it together formally!

@tobie: For your second example, I think it's clear - the "stable"
shortlink goes to the level 1 CR, the "ed" shortlink goes to the level
2 ED. I presume it's up to the WG to report that a new ED is being
used, as they're not officially published.

For your first example, tho, I echo your concerns. CSS has examples
of this, either current or in the recent past. We need a simple,
objective, and useful criteria for deciding whether the "stable"
shortlink points to level 1 or level 2 in that example. I think that
pointing to level 2 (the CR) is the correct choice here.

~TJ
Florian Rivoal
2016-12-17 06:17:27 UTC
Permalink
Post by Tobie Langel
Hi all,
Thanks Tobie for starting the thread of that topic. Levels on /TR have
indeed started to cause of a lot of problems because so far, we
don't have a good way to manage the different versions of a
specification.
After discussing with different people, we came up with a document
listing 3 proposals aiming at normalizing the latest version links. It
https://w3c.github.io/tr-links/versioning/
The idea is to introduce new links to help the different
audiences (browser implementors, web developers, etc) find the
version of the specification they are looking for.
Please take a look at the document and I encourage you to create
issues on the Github repository [1] if you have any questions/comments.
FYI, I created an issue for each proposal [2][3][4]. Feel free to
comment on it and/or +1 on your preferred proposal.
Thank you,
Denis
[1] https://github.com/w3c/tr-links
[2] https://github.com/w3c/tr-links/issues/1
[3] https://github.com/w3c/tr-links/issues/2
[4] https://github.com/w3c/tr-links/issues/3
This is interesting, but I think it is missing on two critical pieces: how these various drafts get produced, and the fact that there is typically not a single ED that represents the bleeding edge, but 1 ED per level, the latest of which typically does represent the bleeding edge, and the others being preparation for updates to the various TR versions. The fact that these various EDs tend to be updated fairly inconsistently adds a fair bit of confusion, as well as overhead, when the time to reconcile them comes.

The various TR version cannot simply be snapshots of the latest ED at different points in time, since the latest ED typically combines a mix of mature features taken from the previous REC (if any), stabilizing features meant to become the next REC, and foward looking features meant to move to TR after that.

I think that one way to solve this would be to embrace git at a deeper level than we do now, and mandate a particular branching and merging workflow that deals with what we are trying to accomplish.

Here is an example of a possible workflow, presented not as The One True Way, but as food for thought:

- A stable branch
- A staging branch
- A latest branch
- multiple feature or bugfix branches

The stable and staging branches branch would take no direct commit, only merges. Each merge commit on the stable branch would be equivalent to what we today consider a publication on TR. The necessary legal requirements (currently verified in transition calls and the like) would be preconditions to approving a merge to the stable branch

Any change, whether a bug fix or a new feature or an editorial change, must always be done in a separate branch.

* Merging to the latest branch is equivalent to putting something in the ED of the newest level today.
* Merging to the staging branch is equivalent to putting something in the ED of the stabilizing TR version today
* Merging the staging branch to the stable branch would be equivalent to various things depending on the situation:
- there has been no REC or CR yet: equivalent to pushing a new WD out to TR, or to pushing out the first CR if tagged appropriately
- There has been a CR, but no REC yet: equivalent to updating the CR, or to pushing out the first REC if tagged appropriately
- There has been a REC already, and the changes are minor: equivalent to publishing errata on a REC
- There has been a REC already, the the changes are substantial: equivalent to publishing a new level REC
* The Equivalent of PR would be handled by a specially tagged version on the staging branch, to be reviewed there.

This is in line with the way many software project work and manage their release versions, beta versions, nightly channels, and so on.
In my experience, the trickiest part of such workflows is to get people into the habit of starting their feature/bugfix branches not from the tip of the latest branch, but from what they wish to be able to merge into. Something that needs to be independently merge-able into stable/staging (in addition to latest) without bringing unintended dependencies should be branched off stable/staging, although it is possible to work around that by cherry picking changes from latest to staging.

As today for Pull Requests, you would need to go to github directly for the feature branches that have not been merged anywhere yet, but everything else could be exposed to the web through something like this, with appropriate links and redirects generated automatically:

/TR/shortname/
/TR/shortname/stable/
/TR/shortname/stable/YYYYMMDD/
/TR/shortname/staging/
/TR/shortname/staging/YYYYMMDD/
/TR/shortname/latest/
/TR/shortname/latest/YYYYMMDD/
/TR/shortname/index/

—Florian

Continue reading on narkive:
Loading...