Re: Dealing with levels in specs

On Thu, Nov 17, 2016 at 6:08 AM, Tobie Langel <tobie@codespeaks.com> wrote:
> On Wed, Nov 16, 2016, at 19:14, Liam R. E. Quin wrote:
>> On Wed, 2016-11-16 at 09:45 +0100, Tobie Langel wrote:
>> > 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.
>
>> 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.

>> 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).

>> > 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.

> 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?

>> > - 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.
>
>> > - 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.
>
>> > - 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

Received on Saturday, 19 November 2016 00:08:51 UTC