Re: PSA: publish WD of "WebIDL Level 1"

[Yves Lafon]

> On 31 Aug 2015, at 20:12, Ms2ger  wrote:
> 
> -BEGIN PGP SIGNED MESSAGE-
> Hash: SHA1
> 
> Hi Yves,
> 
> On 08/31/2015 03:28 PM, Yves Lafon wrote:
>> In fact, I would prefer to have the editors’ copy published as 
>> TR/WebIDL/, and let -1 -2 … -n be pointers to the stable version 
>> (aka, what is implemented, not what has to be implemented).
>> 
> 
> Who do you propose will construct such a "what is implemented"
> specification, and what useful work would you have them drop for it?

Well, we need tests, of course. There is a test suite that needs to be checked 
again,
and lots of other specs have tests that actually test parts of WebIDL. 
So apart from new functionalities that don’t have test yet (and may by mean of 
other specs testing those), most of the work is to gather existing tests, and I 
am ready to help on that. So I don’t ask anyone to stop doing their usual job, 
especially as it can also help here.
Of course people reviewing tests is always a nice feature, as you know.

> 
> Thanks
> Ms2ger
> -BEGIN PGP SIGNATURE-
> 
> iQEcBAEBAgAGBQJV5JkbAAoJEOXgvIL+s8n27aQH/jCaZRS6ONmC1aklZACK5Iep
> NV5VSxq1H2aHv6rdRiBNygeGzEiwENZUnIzv0r0ebQMCRCvhwXqbm+srV9FlFNdb
> dJ7c41cXNHIk4D1+18vYvK4AenqkHE5zozm4LqoZ8SL+YLRFYyIhpXOsV34R5DnP
> wjyLcEbcFgWmYK2TXTNphhTXEmebM89o4vmGkrKPdYqAwWaWNJz5L6hMZARH7lWq
> eYL0iwo9BQbIfR0gLIpuARvS2oOS0Y7/8gNkMuEQ4h9UHa+hcvsOL0JWI6Zz2vTM
> ZNO3nAE1h5In6DFXmK3ZkIlOpIGgsVsK7KmiIKlvZAOZ9NXui851uYA9j2YQQ3U=
> =ixCO
> -END PGP SIGNATURE-
> 

-- 
Baroula que barouleras, au tiéu toujou t'entourneras.

~~Yves

Re: PSA: publish WD of "WebIDL Level 1"

[Yves Lafon]

> On 01 Sep 2015, at 14:27, Ms2ger  wrote:
> 
> Hi Yves,
> 
> On 09/01/2015 11:30 AM, Yves Lafon wrote:
>> On 31 Aug 2015, at 20:12, Ms2ger  wrote:
>>> On 08/31/2015 03:28 PM, Yves Lafon wrote:
 In fact, I would prefer to have the editors’ copy published as 
 TR/WebIDL/, and let -1 -2 … -n be pointers to the stable version
 (aka, what is implemented, not what has to be implemented).
 
>>> 
>>> Who do you propose will construct such a "what is implemented" 
>>> specification, and what useful work would you have them drop for
>>> it?
>>> 
>> 
>> Well, we need tests, of course. There is a test suite that needs to
>> be checked again, and lots of other specs have tests that actually
>> test parts of WebIDL. So apart from new functionalities that don’t
>> have test yet (and may by mean of other specs testing those), most of
>> the work is to gather existing tests, and I am ready to help on that.
>> So I don’t ask anyone to stop doing their usual job, especially as it
>> can also help here. Of course people reviewing tests is always a nice
>> feature, as you know.
>> 
> 
> I'm not sure I understand your point. Tests will need to be written and
> reviewed, whether "what is implemented" specifications are published or
> not. My question is specifically about the editing of the documents you
> propose to publish as -1 -2 … -n.
> 
As far as editing goes, the editors for level-1 are Travis and myself. No work 
is required from Boris and Cameron.

-- 
Baroula que barouleras, au tiéu toujou t'entourneras.

~~Yves

Re: PSA: publish WD of "WebIDL Level 1"

[Ms2ger]

Hi Yves,

On 09/01/2015 11:30 AM, Yves Lafon wrote:
> On 31 Aug 2015, at 20:12, Ms2ger  wrote:
>> On 08/31/2015 03:28 PM, Yves Lafon wrote:
>>> In fact, I would prefer to have the editors’ copy published as 
>>> TR/WebIDL/, and let -1 -2 … -n be pointers to the stable version
>>> (aka, what is implemented, not what has to be implemented).
>>> 
>> 
>> Who do you propose will construct such a "what is implemented" 
>> specification, and what useful work would you have them drop for
>> it?
>> 
>
> Well, we need tests, of course. There is a test suite that needs to
> be checked again, and lots of other specs have tests that actually
> test parts of WebIDL. So apart from new functionalities that don’t
> have test yet (and may by mean of other specs testing those), most of
> the work is to gather existing tests, and I am ready to help on that.
> So I don’t ask anyone to stop doing their usual job, especially as it
> can also help here. Of course people reviewing tests is always a nice
> feature, as you know.
>

I'm not sure I understand your point. Tests will need to be written and
reviewed, whether "what is implemented" specifications are published or
not. My question is specifically about the editing of the documents you
propose to publish as -1 -2 … -n.

Thanks
Ms2ger

Re: PSA: publish WD of "WebIDL Level 1"

[Ryosuke Niwa]

> On Sep 1, 2015, at 7:27 AM, Anne van Kesteren  wrote:
> 
> On Tue, Sep 1, 2015 at 4:23 PM, Ryosuke Niwa  wrote:
>> I think you’re missing the point.  The point of these documentation is to 
>> know exactly what the patch author was looking at the time he wrote the 
>> patch.  If there was a typo in the spec, that’s an important information.
>> 
>> As for diff’ing what has changed, that’s exactly the use case.  In order to 
>> know what has changed, you need to know what the old spec was.  The living 
>> standard is a total nightmare as far as I’m concerned.
> 
> I guess it depends on your workflow. In any event, does what Domenic
> suggests and has implemented for 
> https://urldefense.proofpoint.com/v2/url?u=https-3A__streams.spec.whatwg.org_=BQIFaQ=eEvniauFctOgLOKGJOplqw=051zrPFUkWGMfGlKdhy9Uw=dmgoI6lEFOWkspvfnnlq-RxpY4jfiiozATV5kFegnFY=UcHS2fRzjPxSXuZZ0gQQs5xb3C-Ct3peVtowrZdxoUE=
>  
> address your concern?

Yes!  It totally does.

- R. Niwa

Re: PSA: publish WD of "WebIDL Level 1"

[Ryosuke Niwa]

> On Aug 31, 2015, at 8:51 PM, Anne van Kesteren  wrote:
> 
> On Tue, Sep 1, 2015 at 2:33 AM, Ryosuke Niwa  wrote:
>> Let's say we implement some feature based on Web IDL published as of today.  
>> I'm going to refer that in my source code commit message.  Future readers of 
>> my code has no idea what I was implementing when they look at my commit 
>> message in five years if it refers to the living standard that changes over 
>> time.
> 
> Apart from what Domenic said, IDs should remain stable over time and
> other than features getting expanded, they need to remain backwards
> compatible, just as your code base. (It also seems like useful
> information to know what you've implemented has been refactored or
> changed in some way in the corresponding standard, so you can take
> steps to update your code.)

I think you’re missing the point.  The point of these documentation is to know 
exactly what the patch author was looking at the time he wrote the patch.  If 
there was a typo in the spec, that’s an important information.

As for diff’ing what has changed, that’s exactly the use case.  In order to 
know what has changed, you need to know what the old spec was.  The living 
standard is a total nightmare as far as I’m concerned.

- R. Niwa

Re: PSA: publish WD of "WebIDL Level 1"

[Anne van Kesteren]

On Tue, Sep 1, 2015 at 4:23 PM, Ryosuke Niwa  wrote:
> I think you’re missing the point.  The point of these documentation is to 
> know exactly what the patch author was looking at the time he wrote the 
> patch.  If there was a typo in the spec, that’s an important information.
>
> As for diff’ing what has changed, that’s exactly the use case.  In order to 
> know what has changed, you need to know what the old spec was.  The living 
> standard is a total nightmare as far as I’m concerned.

I guess it depends on your workflow. In any event, does what Domenic
suggests and has implemented for https://streams.spec.whatwg.org/
address your concern?


-- 
https://annevankesteren.nl/

Re: PSA: publish WD of "WebIDL Level 1"

[Ms2ger]

-BEGIN PGP SIGNED MESSAGE-
Hash: SHA1

Hi Yves,

On 08/31/2015 03:28 PM, Yves Lafon wrote:
> In fact, I would prefer to have the editors’ copy published as 
> TR/WebIDL/, and let -1 -2 … -n be pointers to the stable version 
> (aka, what is implemented, not what has to be implemented).
> 

Who do you propose will construct such a "what is implemented"
specification, and what useful work would you have them drop for it?

Thanks
Ms2ger
-BEGIN PGP SIGNATURE-

iQEcBAEBAgAGBQJV5JkbAAoJEOXgvIL+s8n27aQH/jCaZRS6ONmC1aklZACK5Iep
NV5VSxq1H2aHv6rdRiBNygeGzEiwENZUnIzv0r0ebQMCRCvhwXqbm+srV9FlFNdb
dJ7c41cXNHIk4D1+18vYvK4AenqkHE5zozm4LqoZ8SL+YLRFYyIhpXOsV34R5DnP
wjyLcEbcFgWmYK2TXTNphhTXEmebM89o4vmGkrKPdYqAwWaWNJz5L6hMZARH7lWq
eYL0iwo9BQbIfR0gLIpuARvS2oOS0Y7/8gNkMuEQ4h9UHa+hcvsOL0JWI6Zz2vTM
ZNO3nAE1h5In6DFXmK3ZkIlOpIGgsVsK7KmiIKlvZAOZ9NXui851uYA9j2YQQ3U=
=ixCO
-END PGP SIGNATURE-

Re: PSA: publish WD of "WebIDL Level 1"

[Ryosuke Niwa]

> On Aug 7, 2015, at 9:27 AM, Anne van Kesteren  wrote:
> 
> On Fri, Aug 7, 2015 at 6:23 PM, Travis Leithead
>  wrote:
>> This is, at a minimum, incremental goodness. It's better than leaving the 
>> prior L1 published document around--which already tripped up a few folks on 
>> my team recently. I strongly +1 it.
> 
> If your team looks at the newer L1 they will also trip themselves up.
> Anything but https://heycam.github.io/webidl/ is problematic.

For our internal documentation purposes, I'd refer having a perm link to a 
document that never changes.

Let's say we implement some feature based on Web IDL published as of today.  
I'm going to refer that in my source code commit message.  Future readers of my 
code has no idea what I was implementing when they look at my commit message in 
five years if it refers to the living standard that changes over time.

- R. Niwa

RE: PSA: publish WD of "WebIDL Level 1"

[Domenic Denicola]

From: Ryosuke Niwa [mailto:rn...@apple.com]

> For our internal documentation purposes, I'd refer having a perm link to a
> document that never changes.
> 
> Let's say we implement some feature based on Web IDL published as of
> today.  I'm going to refer that in my source code commit message.  Future
> readers of my code has no idea what I was implementing when they look at
> my commit message in five years if it refers to the living standard that
> changes over time.

I agree this is an important use case. Fortunately it is covered by commit 
snapshot URLs. E.g. 
https://rawgit.com/heycam/webidl/a90316a16f639aaa3531208fc0451a1b79a35a7d/index.html

This is better than expecting that the one time a snapshot happens ("v1"), it 
also aligns with what you're implementing at the time.

(BTW: for streams I have made this concept first-class; at 
https://streams.spec.whatwg.org/ you can click the "Snapshot as of this commit" 
link to get 
https://streams.spec.whatwg.org/commit-snapshots/5bd0ab1af09153fd72745516dadc27103e84043c/.)

Re: PSA: publish WD of "WebIDL Level 1"

[Anne van Kesteren]

On Tue, Sep 1, 2015 at 2:33 AM, Ryosuke Niwa  wrote:
> Let's say we implement some feature based on Web IDL published as of today.  
> I'm going to refer that in my source code commit message.  Future readers of 
> my code has no idea what I was implementing when they look at my commit 
> message in five years if it refers to the living standard that changes over 
> time.

Apart from what Domenic said, IDs should remain stable over time and
other than features getting expanded, they need to remain backwards
compatible, just as your code base. (It also seems like useful
information to know what you've implemented has been refactored or
changed in some way in the corresponding standard, so you can take
steps to update your code.)


-- 
https://annevankesteren.nl/

Re: PSA: publish WD of "WebIDL Level 1"

[Yves Lafon]

> On 07 Aug 2015, at 14:45, Arthur Barstow  wrote:
> 
> On 8/4/15 2:21 PM, Tab Atkins Jr. wrote:
>> On Thu, Jul 30, 2015 at 7:29 AM, Arthur Barstow  
>> wrote:
>>> Hi All,
>>> 
>>> This is heads-up re the intent to publish a Working Draft of "WebIDL Level
>>> 1" (on or around August 4) using Yves' document as the basis and a new
>>> "shortname" of "WebIDL-1":
>>> 
>>> 
>>> 
>>> There is an open question about what should happen with TR/WebIDL/ (which
>>> now is the 2012 Candidate Recommendation). One option is to serve it as
>>> WebIDL-1. Another option is to replace it with the latest version of
>>> Cameron's Editor's Draft. A third option is to make it some type of "landing
>>> page" the user can use to load the various versions. Feedback on these
>>> options is welcome and the default (if there are no non-resolvable issues)
>>> is to go with option #2 (Yves' preference).
>> The CSSWG always points the non-leveled url to the latest spec.
> 
> This is also what PLH recommended be done and that seems reasonable to me. 
> Thus:
> 
> TR/WebIDL/ -> TR/WebIDL-2/
> TR/WebIDL-1/
> TR/WebIDL-2/
> 
> The L2 version (by Cameron and Boris [L2]) has not been published as a TR and 
> if there no objections to proceeding as above, I will start working on making 
> this all happen.
> 
In fact, I would prefer to have the editors’ copy published as TR/WebIDL/, and 
let -1 -2 … -n be pointers to the stable version (aka, what is implemented, not 
what has to be implemented).

> -Thanks, AB
> 
> [L2] 

-- 
Baroula que barouleras, au tiéu toujou t'entourneras.

~~Yves

Re: PSA: publish WD of WebIDL Level 1

[Anne van Kesteren]

On Fri, Aug 7, 2015 at 6:23 PM, Travis Leithead
travis.leith...@microsoft.com wrote:
 This is, at a minimum, incremental goodness. It's better than leaving the 
 prior L1 published document around--which already tripped up a few folks on 
 my team recently. I strongly +1 it.

If your team looks at the newer L1 they will also trip themselves up.
Anything but https://heycam.github.io/webidl/ is problematic.


-- 
https://annevankesteren.nl/

Re: PSA: publish WD of WebIDL Level 1

[Travis Leithead]

This is, at a minimum, incremental goodness. It's better than leaving the prior 
L1 published document around--which already tripped up a few folks on my team 
recently. I strongly +1 it.


From: Anne van Kesteren ann...@annevk.nl
Sent: Friday, August 7, 2015 5:55 AM
To: Arthur Barstow
Cc: Tab Atkins Jr.; public-webapps
Subject: Re: PSA: publish WD of WebIDL Level 1

On Fri, Aug 7, 2015 at 2:45 PM, Arthur Barstow art.bars...@gmail.com wrote:
 The L2 version (by Cameron and Boris) has not been published as a TR
 and if there no objections to proceeding as above, I will start working on
 making this all happen.

I still don't understand why L1 is even published. It cannot be
implemented so only furthers confusion.


--
https://annevankesteren.nl/

Re: PSA: publish WD of WebIDL Level 1

[Tab Atkins Jr.]

On Fri, Aug 7, 2015 at 9:23 AM, Travis Leithead
travis.leith...@microsoft.com wrote:
 This is, at a minimum, incremental goodness. It's better than leaving the 
 prior L1 published document around--which already tripped up a few folks on 
 my team recently. I strongly +1 it.

There are alternatives!  In particular, you can publish a gravestone
revision.  Bikeshed has boilerplate for this you can steal the wording
of:

```
details open class='annoying-warning'
  summaryThis Document Is Obsolete and Has Been Replaced/summary
  p
This specification is obsolete and has been replaced by the
document at a href=[REPLACEDBY][REPLACEDBY]/a.
Do not attempt to implement this specification.
Do not refer to this specification except as a historical artifact.
/details
```

Just publish a new WD containing *only* that as the content, and
you're golden.

For bonus points, publish revisions of all the dated webidl1 specs,
with that as an actual warning (no need to wipe out their contents).
Look at the styling of the message on
https://tabatkins.github.io/specs/respimg/ for a good example that
makes it impossible to miss that you're looking at an obsolete spec.

~TJ

Re: PSA: publish WD of WebIDL Level 1

[Arthur Barstow]

On 8/4/15 2:21 PM, Tab Atkins Jr. wrote:

On Thu, Jul 30, 2015 at 7:29 AM, Arthur Barstow art.bars...@gmail.com wrote:

Hi All,

This is heads-up re the intent to publish a Working Draft of WebIDL Level
1 (on or around August 4) using Yves' document as the basis and a new
shortname of WebIDL-1:

https://ylafon.github.io/webidl/publications/fpwd-20150730.html

There is an open question about what should happen with TR/WebIDL/ (which
now is the 2012 Candidate Recommendation). One option is to serve it as
WebIDL-1. Another option is to replace it with the latest version of
Cameron's Editor's Draft. A third option is to make it some type of landing
page the user can use to load the various versions. Feedback on these
options is welcome and the default (if there are no non-resolvable issues)
is to go with option #2 (Yves' preference).

The CSSWG always points the non-leveled url to the latest spec.


This is also what PLH recommended be done and that seems reasonable to 
me. Thus:


TR/WebIDL/ - TR/WebIDL-2/
TR/WebIDL-1/
TR/WebIDL-2/

The L2 version (by Cameron and Boris [L2]) has not been published as a 
TR and if there no objections to proceeding as above, I will start 
working on making this all happen.


-Thanks, AB

[L2] http://heycam.github.io/webidl/

Re: PSA: publish WD of WebIDL Level 1

[Anne van Kesteren]

On Fri, Aug 7, 2015 at 2:45 PM, Arthur Barstow art.bars...@gmail.com wrote:
 The L2 version (by Cameron and Boris) has not been published as a TR
 and if there no objections to proceeding as above, I will start working on
 making this all happen.

I still don't understand why L1 is even published. It cannot be
implemented so only furthers confusion.


-- 
https://annevankesteren.nl/

Re: PSA: publish WD of WebIDL Level 1

[Tab Atkins Jr.]

On Thu, Jul 30, 2015 at 7:29 AM, Arthur Barstow art.bars...@gmail.com wrote:
 Hi All,

 This is heads-up re the intent to publish a Working Draft of WebIDL Level
 1 (on or around August 4) using Yves' document as the basis and a new
 shortname of WebIDL-1:

 https://ylafon.github.io/webidl/publications/fpwd-20150730.html

 There is an open question about what should happen with TR/WebIDL/ (which
 now is the 2012 Candidate Recommendation). One option is to serve it as
 WebIDL-1. Another option is to replace it with the latest version of
 Cameron's Editor's Draft. A third option is to make it some type of landing
 page the user can use to load the various versions. Feedback on these
 options is welcome and the default (if there are no non-resolvable issues)
 is to go with option #2 (Yves' preference).

The CSSWG always points the non-leveled url to the latest spec.  (#2,
if I'm counting your options correctly)

~TJ