Bug 80692 – MediaStream API (JSEP): Rename PeerConnection to DeprecatedPeerConnection

• Status: RESOLVED
• Resolution: FIXED
• Component: WebKit API

[Tommy Widenflycht]

First patch in a series of patches to change the PeerConnection from ROAP to JSEP, see bug 80589 for more information.

[Tommy Widenflycht]

Created attachment 131019 [details]
Patch

[Tommy Widenflycht]

Contains zero code changes apart from renames.

[WebKit Review Bot]

Comment on attachment 131019 [details]
Patch

Attachment 131019 [details] did not pass chromium-ews (chromium-xvfb):
Output: http://queues.webkit.org/results/11911513

New failing tests:
fast/dom/call-a-constructor-as-a-function.html

[Tommy Widenflycht]

Created attachment 131026 [details]
Patch

[Adam Barth]

(Continuing the discussion from Bug 80589:

> > The risk of using a name like JSEPPeerConnection is that we'll be stuck with that as the final name for the API.  If we us PeerConnection for JSEP and change the existing API to DeprecatedPeerConnection, there's no risk of getting stuck with the wrong name for the final API.
> 
> Isn't the final name pending until the prefixes are removed anyhow? But I agree that JSEPPeerConnection is bad. ExperimentalPeerConnection would be better IMO.

Right, we're talking about webkitPeerConnection, which means "experimental PeerConnection" already.  Writing "experimental" into the name twice is redundant.

> > Also, using this naming arrangement encourages folks to move over to the new API, making it easier for us to remove DeprecatedPeerConnection when that's appropriate.
> 
> The discussion is still ongoing in W3C on which changes JSEP will have on the API. It shouldn't prevent anyone from prototyping though.

I think this is where the biggest disconnect in this discussion lives.  Tommy tells me that the JSEP design has already been accepted by the standards community and you're telling me that it hasn't.  I haven't been following the standard discussion closely.  Can one or both of you clarify the status of the new API design w.r.t. the various working groups?

[Harald Tveit Alvestrand]

I could repeat my status message from #80589, but that seems superfluous - we all agree that JSEP is the thing that will happen, what we don't know (or agree on?) is how stable the current specification is.

The latest spec is draft-uberti-jsep-02, dated Feb 16. The biggest subsequent discussion has been about the "single offer / multiple answer" scenario; this has much to do with the semantics of the calls, but not so much with their API - that is, I would expect effects of any changes here to be at the Chrome level, not the Webkit level.

[Harald Tveit Alvestrand]

Correction: Latest is draft-ietf-rtcweb-jsep-00 - March 3.
There are no API-impacting changes between these two drafts.

[Tommy Widenflycht]

(In reply to comment #5)
> > The discussion is still ongoing in W3C on which changes JSEP will have on the API. It shouldn't prevent anyone from prototyping though.
> 
> I think this is where the biggest disconnect in this discussion lives.  Tommy tells me that the JSEP design has already been accepted by the standards community and you're telling me that it hasn't.  I haven't been following the standard discussion closely.  Can one or both of you clarify the status of the new API design w.r.t. the various working groups?

I have followed the email lists and participated in the WebRtc hangouts and the discussion I have seen is not regarding the actual API, but related to how the SDP messages should work. Also Justins proposal have been upgraded to be an "official" proposal as Harald wrote. I have based my comments on this, and the confirmation from Justing and Harald.

If I have missed an active API discussion I am truly sorry and would appreciate a pointer to where that is happening so that I can monitor the state of JSEP better.

[Adam Bergkvist]

(In reply to comment #5)
> > The discussion is still ongoing in W3C on which changes JSEP will have on the API. It shouldn't prevent anyone from prototyping though.
> 
> I think this is where the biggest disconnect in this discussion lives.  Tommy tells me that the JSEP design has already been accepted by the standards community and you're telling me that it hasn't.  I haven't been following the standard discussion closely.  Can one or both of you clarify the status of the new API design w.r.t. the various working groups?

You're probably right.

JSEP (JavaScript Session Establishment Protocol) has been adopted as a Working Group document by the RTCWeb working group in IETF. The vote at the IETF interim meeting in January made it pretty clear that people prefer JSEP over ROAP (RTCWeb Offer Answer Protocol) which was the previous signaling protocol.

The JSEP document comes with an API proposal, but the final say about the API lies within the WebRTC working group in W3C. There are currently two API proposals: the JSEP API, as proposed in the JSEP draft, and a proposal that adopts the existing API to use JSEP (as signaling protocol). Both proposals are currently being edited into the spec in separate experimental branches on github.

I would like to repeat that I think experimental prototyping is essential. I think we simply have different opinions on what's deprecated at this point.

[Adam Bergkvist]

(In reply to comment #8)
> If I have missed an active API discussion I am truly sorry and would appreciate a pointer to where that is happening so that I can monitor the state of JSEP better.

The API discussions have mainly been on [e-mail]. Regarding the experimental JSEP branches in github, it's all publicly available, but I don't think it's been communicated outside the editor/chairs team.

Discussions about the JSEP API:
http://lists.w3.org/Archives/Public/public-webrtc/2012Feb/0044.html
http://lists.w3.org/Archives/Public/public-webrtc/2012Jan/0093.html

Experimental JSEP branches in github (work in progress):
https://github.com/fluffy/webrtc-w3c/tree/jsep1
https://github.com/fluffy/webrtc-w3c/tree/jsep_easy1

[Adam Barth]

I talked some more with Harald.  My understanding is that everyone agrees on the following points:

1) The existing API design is going to change substantially, likely in the direction of JSEP.
2) The current draft of JSEP is also unlikely to be the final version of the API.
3) There's some political sensitivity to us "picking a winner" while the working group continues to discuss the topic.

From that standpoint, the following plan seems to make sense:

1) Rename the existing webkitPeerConnection to webkitDeprecatedPeerConnection.  Folks will be able to keep their demos working with a simple renaming, but doing so will let them know that big changes to the API are coming and they'll need to update to the new design at some point.

2) Introduce the current JSEP as webkitPeerConnection00.  More forward with implementation will let us get implementation experience with the new design, which will improve the quality of the final API.  The 00 suffix serves to reassure folks that we're not trying to "pick a winner" in this discussion, merely that we're trying to gain implementation experience.

3) As soon as the W3C spec is updated to the JSEP design, we'll rename webkitPeerConnection00 to webkitPeerConnection and continue to track the spec as it evolves.  Having an off-by-default, prefixed implementation track a spec as it evolves is the standard operating procedure and should be something that folks understand.

4) After (3) and after the JSEP implementation is sufficiently functional to support existing demos that are using webkitDeprecatedPeerConnection, we'll delete webkitDeprecatedPeerConnection.  It's important to delete webkitDeprecatedPeerConnection relatively soon because we don't want to be stuck implementing it forever.  Also, deleting webkitDeprecatedPeerConnection will cause folks to switch to webkitPeerConnection and give us more feedback on the new design.

[Adam Bergkvist]

(In reply to comment #11)
> I talked some more with Harald.  My understanding is that everyone agrees on the following points:
> 
> 1) The existing API design is going to change substantially, likely in the direction of JSEP.

The alternative API that is being drafted on github basically runs JSEP under the existing API so this depends on what we decide to do.

> 2) The current draft of JSEP is also unlikely to be the final version of the API.
> 3) There's some political sensitivity to us "picking a winner" while the working group continues to discuss the topic.

I agree to the two points above.

> From that standpoint, the following plan seems to make sense:

Couldn't we just introduce the new PeerConnection as PeerConnection00 and as soon as the W3C working draft is updated, what ever the result is, it will become PeerConnection?

[Harald Tveit Alvestrand]

>
> --- Comment #12 from Adam Bergkvist<[e-mail]>   2012-03-13 08:37:26 PST ---
> (In reply to comment #11)
>> I talked some more with Harald.  My understanding is that everyone agrees on the following points:
>>
>> 1) The existing API design is going to change substantially, likely in the direction of JSEP.
> The alternative API that is being drafted on github basically runs JSEP under the existing API so this depends on what we decide to do.

To be precise: The alternative API that you're drafting on github.

And even that API will not be interoperable with implementations of the old API; my suspicion is that applications written to the old API won't work with the new one either, without significant kludging at the API level.

So that proposal is likely to require code changes too.
>> 2) The current draft of JSEP is also unlikely to be the final version of the API.
>> 3) There's some political sensitivity to us "picking a winner" while the working group continues to discuss the topic.
> I agree to the two points above.
>
>>  From that standpoint, the following plan seems to make sense:
> Couldn't we just introduce the new PeerConnection as PeerConnection00 and as soon as the W3C working draft is updated, what ever the result is, it will become PeerConnection?

I would prefer to get the old PeerConnection, and all code that depends on it continuing to work exactly the way it does now, clearly marked with "yes, I know that I'm using something that will go away".

[Adam Barth]

Comment on attachment 131026 [details]
Patch

It seems like there's still some debate in the working group about what the future of the API is going to look like.  The working group is a much better place to have that debate than this bug tracker.  I think renaming this object is a reasonable step to letting folks know that the API in a state of flux.  The steps I've outlined above should keep WebKit relatively neutral in this debate as none of the candidates will be named "webkitPeerConnection".

IMHO, this naming discussion is a distraction from the work of creating the best API.

[WebKit Review Bot]

Comment on attachment 131026 [details]
Patch

Clearing flags on attachment: 131026

Committed r110587: <http://trac.webkit.org/changeset/110587>

[WebKit Review Bot]

All reviewed patches have been landed.  Closing bug.