Hi Andrew, Below is a review of the document. I've included the text and responded inline…
On Sunday, 7 July 2013 at 15:24, Marcos Caceres wrote: > Guidelines > > Mozilla aims to advance the state of the open web with new APIs. Toward this > end, > > Mozilla will not hurt the web by exposing a new web API in such a way that a > web developer can detect it (1) before it's ready. I think "hurt" in the above is a bit too, um, I don't know… emotional? Maybe: In the last few years, Mozilla shipped experimental APIs with a "moz" prefix to indicate their lack of standardization (e.g., mozRequestAnimationFrame()). Unfortunately, this approach turned out to be harmful to the Web as experimental APIs ended up being used in websites before the APIs were ready. In many cases, this meant that we were unable to innovate on certain APIs because to change them would break content on the Web. To allow us to continue innovating without affecting content on the Web, Mozilla will no longer directly expose experimental APIs to the Web Platform using a vendor prefix. Instead, developers who want to road test experimental APIs, will need to explicitly enable them by going through `about:config`. Once we have agreement in the Web community about the stability of an API, and we feel it is ready, then we will make it generally available to the platform (more details below on this policy). We feel this strikes the right balance between allowing developers to experiment with new APIs, while at the same time protecting the Web from being exposed to new functionality prematurely. For more details, see Henri Sivonen's proposal. > > In the past we have shipped APIs with "moz" prefixes to indicate their lack > of standardization but we no longer do this. See Henri Sivonen's proposal. > > Mozilla will not ship moz-prefixed web APIs > > Scope > > At this time, we are specifically focusing on new web APIs and non-trivial > changes to existing APIs. We are explicitly not focusing on CSS, WebGL, > WebRTC, network protocols, or other existing features/properties. In the > future, pending module owner agreement, we may extend this policy beyond web > APIs to other web-exposed features. I think the above is a bad idea. Specially with regards to CSS, WebGL, etc. All experimental things should be behind a flag. > When is an API ready to be shipped by Gecko? > > APIs which Mozilla makes available by default to the web on the release > channel should be standardized. This can mean that they are de jure standards > (ex. W3C recommendations) or de facto standards. Indications that an API is > standardized enough for shipping to the open web include: > > other browser engines ship compatible implementations, either in their > release or in other channels with clear signals it will graduate to a release > other browser engines state their intention to ship a compatible > implementation > there exists a specification that is no longer at risk of significant > changes, is on track to become a standard with a relevant standards body, and > is acceptable to a number of applicable parties and other browser engines Agree… though they are all a bit abstract. How is compatibility assessed (test suite, obviously… but still… or is it content)? Apart from the Google Dashboard, I think there was a table at the WHATWG of who has given a signal to support a particular part of HTML (at least). We should probably gather the things that will inform the above in some open and transparent manner. > > Mozilla seeks feedback from other browser engines during development and > implementation of web APIs. How do we do this? > Lack of feedback will not stop our efforts "Our efforts" is ambiguous: do you mean efforts to continue innovating or efforts to seek feedback? > as it may simply indicate lack of interest at that time from another browser > engine. We will attempt to reciprocate this feedback to other browser engines > when they are developing a feature or API that we believe to/will be > relevant, even if we won't implement it ourselves in the short term. We should mention that we will be coordinating with the Chrome team with regards to this? Be good if we could also get some other browser folks to commit. > Exceptions Maybe "Proprietary Features"? It's not really about about making an exceptions - as we won't make any exceptions for things that are for "the platform". > > New user-facing products like Firefox OS may need It's not "may need to". It's a matter of fact that we do this - and we should not be sheepish about it. > to ship APIs that have not yet been embraced by other browser engines or > thoroughly discussed by standards bodies. Products such as Firefox OS would > ship these APIs as a part of their product but not to the broader web, thus > clearly indicating their lack of standardization and limiting the number of > web developers relying upon them. When rare situations such as this arise, > API standardization must begin within one year of shipping the initial > version of such products. I think we need to state more clearly why we make proprietary things, like: FireFox OS has allowed Mozilla to innovate at a faster pace than would be possible through a standards organisation. Because FireFox OS is a proprietary platform, we are able to provide certain functionality that is not yet generally available to the Web (e.g., telephony, NFC, Bluetooth, and USB access). From what we have learned from building FireFox OS, we directly inform various W3C specifications that are now under development. Our aim is to standardise our proprietary APIs so they become available on royalty free basis for the benefit of the Web community at large. > Since APIs will very likely change as they are standardized and some > developers will build things on top of non-standardized versions of these > APIs, we will try to reasonably assist affected developers where possible. > Should an API's standardization process fail, it is unclear what will be done > with the non-standard API that has been shipped since some people will surely > be relying upon it, even if it is only a part of one product and not > available to the web at large. FIXME should we ship these APIs prefixed or > under a window.mozilla namespace or just with their "normal" name? These should remain hidden from the Web… hosted apps are going to make things really complicated here… but at least window.navigator.mozApps.install might save us from some of that. > Implementation Process > > If your work is going to expose a new web API to the web or non-trivially > change an existing API, it is requested that you follow these steps: The above is now speaking to an internal audience, while previous sections of this document were talking to an external audience. Please make this clear. > > Email dev-platform declaring your intent to implement this API (FIXME CC > joint list with Blink) (FIXME create email template (Blink's template)). If > you are implementing an API that is working its way through a standards body > process such as the W3C's, it's best to email as soon as possible (ie. before > W3C CR status if possible). > Implement as normal. Code review rounds will take place, etc. I'm worried that anyone can basically declare the intent to implement any API. How do Web developers themselves get a say in what should be implemented (i.e., our users/devs should have a way to influence the priority based on what they need)? Or, those proposing to implement something should also need to demonstrate that this is something Web devs are asking for and it would benefit end-users… I guess this probably happens by default, but it's good to be clear on such things. > We are creating a Mozilla API review team which will be made up of Mozillians > who have experience designing JS APIs and will have at least one > representative from the JS team at all times. This team will monitor > dev-platform for intent to implement emails and can assist with ensuring APIs > are "webby" and friendly to JS developers. When new APIs are being > implemented, a super-review from a member of the API review team (once it is > in place) is requested. Module owners can choose to waive this request if > they feel it is not necessary. Feedback on the above has already been given in the thread (about API design being outside the control of Mozilla) - I tend to agree that the above somewhat problematic. I think the above should be dropped. If anything, we should work more closely with the people mentioned above during the specification phase, not the implementation phase (even if they happen together). There are lots of ways of doing this, like creating prototypes, reaching out to key individuals from the JS community, etc. On Thursday, 4 July 2013 at 16:06, Andrew Overholt wrote: > Thank you to everyone that provided feedback. I've read everyone's > comments and taken them into account with my new draft: > > https://wiki.mozilla.org/User:Overholt/APIExposurePolicy > > In general I tried to make it more of a set of requests and guidelines > than a set of "must"s. I also clarified some of the wording around what > it means for something to be "standardized" or "ready for shipping". > > It's ready for another round of feedback when people have time. > > Thanks again! > > Andrew > _______________________________________________ > dev-platform mailing list > dev-platform@lists.mozilla.org (mailto:dev-platform@lists.mozilla.org) > https://lists.mozilla.org/listinfo/dev-platform -- Marcos Caceres _______________________________________________ dev-platform mailing list dev-platform@lists.mozilla.org https://lists.mozilla.org/listinfo/dev-platform
