WebAPI/WebIDL Review Checklist

From MozillaWiki
Jump to: navigation, search

A review checklist for DOM Peers while doing WebIDL reviews. Not yet complete.

  • Assuming the API is exposed to the Web (so especially non-b2g-only APIs), make sure the API follows the spec.
  • The API should be easy to understand and use, and consistent.
  • If the API has [Exposed=SomethingOtherThanWindow]:
    • Audit the API implementation to make sure it doesn't assume the existence of a Window or a Document
    • Require basic test coverage for each of the contexts in which the API is exposed.
  • Use of [CheckPermissions] and [AvailableIn] should be preferred to doing permission checks or checks for privileged or certified apps in the implementation.
  • If an API is only intended for privileged or certified apps, it should use [AvailableIn], even if it is also controlled by a permission (in which case it requires a [CheckPermissions] in addition to [AvailableIn]).
  • Please take extra care reviewing things that are hidden behind [Pref]s. If an API only has a [Pref] annotation, and it's supposed to be something only available to a subset of Firefox OS apps, they are probably doing things wrong, because [Pref] only gives us platform level granularity. IOW, when they turn on the pref on b2g, the API will end up being exposed to all content there, which is usually not what we want. Currently the only legitimate use case for only using [Pref] without either <code>[CheckPermissions] or [AvailableIn] is for APIs that are supposed to be exposed to all Web content but we're not turning them on yet for spec or implementation stability reasons.
  • Consider whether APIs are acceptable for prerendering. See https://wiki.mozilla.org/Gecko:Prerendering/API_Review_Guidelines for more information.
  • Please refer to the WebIDL spec or the documentation for our binding layer in order to double check your understanding of the IDL as needed.