Issues ====== This draft API reflects a good guess at a useful, efficent API for storing user-contributed compatibility data. Some of the guesses are better than others. This section highlights the areas where more experienced opinions are welcome, and areas where more work is expected. .. contents:: Additions to Browser Compatibility Data Architecture ---------------------------------------------------- This spec includes changes to the `Browser Compatibility Data Architecture`_ developed around March 2014. These seemed like a good idea to me, based on list threads and thinking how to recreate Browser Compatibility tables live on MDN. These changes are: * browsers_ - **slug** - human-friendly unique identifier - **name** - converted to localized text. - **note** - added for engine, OS, etc. information * versions_ - Was `browser-versions`, but multi-word resources are problematic. - **release_day** - Day of release - **retirement_day** - Day of "retirement", or when it was superceeded by a new release. - **status** - One of `"retired"`, `"retired-beta"`, `"current"`, `"beta"`, `"future"` - **relese_notes_uri** - For Mozilla releases, as specified in CompatGeckoDesktop_. - **note** - added for engine version, etc. * features_ - **slug** - human-friendly unique identifier - **mdn_uri** - MDN page that data was scraped from - **experimental** - True if the feature is considered experimental due to being part of a unratified spec such as CSS Transitions, ES6, or the DOM Living Standard. For example, see the `run-in` value of `Web/CSS/display`_. - **standardized** - True if the feature is described in a standards-track specification, regardless of the maturity of the specification. Most features are standardized, but some browser-specific features may be non-standard, and some features like the `left` and `right` features of `Web/CSS/caption-side`_ were part of the CSS2 "wishlist" document that was not standardized. - **stable** - True if the feature is considered stable enough for production usage. - **obsolete** - True if the feature should no longer be used in production code. - **name** - converted to localized text, or a string if the name is canonical - **sections** - replaces spec link - **parent**, **children** - tree relations for this feature * supports_ - Was `browser-version-features`, but multi-word resources are problematic. - **prefix** - string prefix to enable, or null if no prefix - **prefix_mandatory** - True if the prefix is required - **alternate_name** - An alternate name associated with this feature, such as `"RTCPeerConnectionIdentityEvent"` - **alternate_name_mandatory** - True if the alternate name is required - **requires_config** - A configuration string required to enable the feature, such as `"media.peerconnection.enabled=on"` - **default_config** - The configuration string in the shipping browser, such as `"media.peerconnection.enabled=off"` - **note** - Note, which can be null, but if included, can be translated, and may contain HTML and code samples. Supports extended footnote in use on MDN. MDN inline notes are not supported, and must be converted to footnotes. There are also additional Resources_: * specifications_ - For referring to a specification, with translated titles and URIs. * sections_ - For referring to a section of a specification, with translated titles and anchors * maturities_ - For identifying the process stage of a specification * All the history_ resources (historical_browsers_, historical_versions_, etc.) * users_ - For identifying the user who made a change * changesets_ - Collect several history resources into a logical change Unresolved Issues ----------------- * We've been talking data models. This document talks about APIs. **The service will not have a working SQL interface**. Features like history require that changes are made through the API. Make sure your use case is supported by the API. * overholt wants `availability in Web Workers`_. Is an API enough to support that need? * I think Niels Leenheer has good points about browsers being different across operating systems and OS versions - I'm considering adding this to the model: `Mapping browsers to 2.2.1 Dictionary Browser Members`_. * How should we support versioning the API? There is no Internet concensus. - I expect to break the API as needed while implementing. At some point (late 2014), we'll call it v1. - Additions, such as new attributes and links, will not cause an API bump - Some people put the version in the URL (/v1/browsers, /v2/browsers) - Some people use a custom header (``X-Api-Version: 2``) - Some people use the Accept header (``Accept: application/vnd.api+json;version=2``) - These people all hate each other. `Read a good blog post on the subject`_. * What should be the default permissions for new users? What is the process for upgrading or downgrading permissions? * Is Persona a good fit for creating API accounts? There will need to be a process where an MDN user becomes an API user, and a way for an API user to authenticate directly with the API. * If we succeed, we'll have a detailed history of browser support for each feature. For example, the datastore will know that every version of Firefox supported the ``

`` tag. How should version history be summarized for the Browser Compatibility table? Should the API pick the "important" versions, and the KumaScript display them all? Or should the API send all known versions, and the KumaScript parse them for the significant versions, with UX for exposing known versions? The view doc proposes one implementation, with a ```` section for identifying the important bits. * Do we want to add more items to versions? Wikipedia has interesting data for `Chrome release history`_ and `Firefox release history`_. Some possibly useful additions: release date, retirement date, codename, JS engine version, operating system, notes. It feels like we should import the data from version-specific KumaScripts like CompatGeckoDesktop_ (versions, release dates, translations, links to release docs). * We'll need additional models for automated browser testing. Things like user agents, test names, test results for a user / user agent. And, we'll need a bunch of rules for mapping test results to features, required number of tests before we'll say a browser supports a feature, what to do with test conflicts, etc. It might be easier to move all those wishlist items to a different project, that talks to this API when it's ready to assert browser support for a feature. * We need to decide on the URIs for the API and the developer resources. This is being tracked by `Bugzilla 1050458`_. * In browsers_, it seems like icon won't be generally useful. What format should the icon be? What size? It may be more useful to use the slug for deciding between icons designed for the local implementation. Interesting MDN Pages --------------------- These MDN pages represent use cases for compatibility data. They may suggest features to add, or existing features that will be dropped. * `Web/HTML/Element/address`_ - A typical "simple" example. However, the name is non-canonical ("Basic Features") and must be translated, rather than a canonical form ("`
`") that could be the same for all languages. * `Web/CSS/display`_ - This complex page includes non-canonical names ("``none,inline`` and ``block``"), experimental features (``run-in``), support changes across versions, prefixes, etc. Everything that makes this project hard. * `Web/CSS/cursor`_ - May be more complex than `display`. * `Web/HTML/Element/Input`_ - Complex, with lots of attributes. Split by standard may not be as useful as other ways to split it. * `Web/CSS/animation-name`_ - New property that moved from prefixed support to standard support. * `Web/CSS/caption-side`_ - Rarely used 'Non-standard' tag. Also seen on `Web/CSS/text-align`_. * `Web/CSS/@font-face`_ - Rarely used 'Unimplemented' tag as inline note. Also seen on `Web/CSS/text-decoration-line`_. * `Web/CSS/length`_ - Rarely used "warning" tag. Also seen on `Web/CSS/text-underline-position`_. * `Web/CSS/line-break`_ - Rarely used "Fix Me" inline note * `Web/CSS/min-height`_ - "Obsolete since Gecko 22" tag on auto, versus: * `Web/CSS/min-width`_ - Obsolete trash can icon * `Web/CSS/text-transform`_ - Interesting use of non-ascii unicode in feature names, good test case. * `Web/CSS/transform-origin`_ - IE may justify a 'alternate' value for supports.support, or just 'no' with a note. Some pages will require manual intervention to get them into the data store. Here's a sample: * `Web/CSS/box-decoration-break`_ - Broken formatting * `Web/CSS/box-sizing`_ - In Safari column, link to engine version will become an inline note. * `Web/CSS/break-inside`_ - Will need to add a skeleton compatibility table. * `Web/CSS/@document`_ - Specification paragraph rather than normal table. * `Web/CSS/clip`_ - Long inline notes should be converted to notes. * `Web/CSS/:invalid`_ - Links in feature names to other MDN docs * `Web/CSS/outline-color`_ - Instead of version, long note about support. Convert to two versions and a footnote. * `Web/CSS/radial-gradient`_ - Evolving standard, used version notes instead of marking feature as experimental or deprecated. * `Web/CSS/ratio`_ - Strange Chrome version * `Web/CSS/tab-size`_ - Lots of interesting versions, including Safari nightly. * `Web/CSS/text-rendering`_ - convert to footnotes, other changes needed. Not sure if it belongs under CSS. * `Web/API/IDBObjectStore`_ - apoplectic warning of Chrome behaviour. Maybe convert to regular note, or add a Feature for Chrome prefix with non-standard tag? Translating from MDN wiki format -------------------------------- The current compatibility data on developer.mozilla.org in MDN wiki format, a combination of HTML and KumaScript. A MDN page will be imported as a feature with at least one child feature. Here's the MDN wiki version of the Specifications section for `Web/CSS/border-image-width`_: .. code-block:: html

Specifications

Specification Status Comment
{{SpecName('CSS3 Backgrounds', '#border-image-width', 'border-image-width')}} {{Spec2('CSS3 Backgrounds')}} Initial specification
The elements of this table are converted into API data: * **Body row, first column** - Format is ``SpecName('KEY', 'PATH', 'NAME')``. ``KEY`` is the specification.mdn_key, ``PATH`` is section.subpath, in the page language, and ``NAME`` is section.name, in the page language. The macro SpecName_ has additional lookups on ``KEY`` for specification.name and specification.uri (en language only). * **Body row, second column** - Format is ``Spec2('KEY')``. ``KEY`` is the specification.mdn_key, and should match the one from column one. The macro Spec2_ has additional lookups on ``KEY`` for maturity.mdn_key, and maturity.name (multiple languages). * **Body row, third column** - Format is a text fragment which may include HTML markup, becomes the section.name associated with this feature. and here's the Browser compatibility section: .. code-block:: html

Browser compatibility

{{CompatibilityTable}}
Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari
Basic support 15.0 {{CompatGeckoDesktop("13.0")}} 11 15 6
Feature Android Firefox Mobile (Gecko) IE Phone Opera Mobile Safari Mobile
Basic support {{CompatUnknown}} {{CompatGeckoMobile("13.0")}} {{CompatNo}} {{CompatUnknown}} {{CompatUnknown}}
This will be converted to API resources: * **Table class** - one of ``"compat-desktop"`` or ``"compat-mobile"``. Representation in API is TBD. * **Header row, all but the first column** - format is either ``Browser Name (Engine Name)`` or ``Browser Name``. Used for browser.name, engine name is discarded. Other formats or KumaScript halt import. * **Non-header rows, first column** - If the format is ``some text``, then feature.canonical=true and the string is the canonical name. If the format is text w/o KumaScript, it is the non-canonocial name. If there is also KumaScript, it varies. **TODO:** doc KumaScript. * **Non-header rows, remaining columns** - Usually Kumascript: * ``{{CompatUnknown}}`` - version.version is ``null``, and support.support is ``"unknown"`` * ``{{CompatVersionUnknown}}`` - version.version and are ``null``, and support.support in ``"yes"`` * ``{{CompatNo}}`` - version.version and are ``null``, and support.support is ``"no"`` * ``{{CompatGeckoDesktop("VAL")}}`` - version.version is set to ``"VAL"``, support.support is ``"yes"``. and version.release_day is set by logic in CompatGeckoDesktop_. * ``{{CompatGeckoMobile("VAL")}}`` - version.version is set to ``"VAL"``, support.support is ``"yes"``. is set by logic in CompatGeckoMobile_. * Numeric string, such as ``6``, ``15.0``. This becomes the version.version, and support.support is ``"yes"``. * **Content after table** - This is usually formatted as a paragraph, containing HTML. If it resembles a footnote, it will be converted to supports.notes. Once the initial conversion has been done for a page, it may be useful to perform additional steps: 1. Split large features_ into smaller ones. For example, here's one way to reorganize `Web/CSS/display`_: .. image:: ../../_static/canonicalized-display.svg :alt: Reorganization of Web/CSS/display :target: https://rawgit.com/jwhitlock/web-platform-compat/master/docs/_static/canonicalized-display.svg Data sources for browser versions --------------------------------- The **version** model currently supports a release date and a retirement date, as well as other version data. Some sources for this data include: * Google Chrome - `Google Chrome Release History`_ on Wikipedia * Mozilla Firefox - `Firefox Release History`_ on Wikipedia and KumaScript macro CompatGeckoDesktop_ * Microsoft Internet Explorer - `Release History of IE`_ on Wikipedia * Opera - `Current Opera version history`_ and `Presto history`_ on opera.com * Safari - `Safari version history`_ on Wikipedia To Do ----- * Add multi-get to browser doc, after deciding on ``GET /versions/1,2,3,4`` vs. ``GET /browser/1/versions`` * Look at additional MDN content for items in common use * Move to developers.mozilla.org subpath, auth changes * Jeremie's suggested changes (*italics are done*) * *Add browsers.notes, localized, to note things like engine, applicable OS, execution contexts (web workers, XUL, etc.).* * *Drop browsers.engine attribute. Not important for searching or filtering, instead free text in browsers.notes* * *Add versions.notes, localized, to note things like OS, devices, engines, etc.* * *Drop versions.engine-version, not important for searching or sorting.* * Drop versions.status. Doesn't think the MDN team will be able to keep up with browser releases. Will instead rely on users figuring out if a browser version is the current release. * *Drop feature.canonical. Instead, name="string" means it is canonical, and name={"lang": "translation"} means it is non-canonical.* * Feature-sets is a cloud, not a heirarchy. "color=red" is the same feature as "background-color=red", so needs to be multiply assigned. * *A feature-set can either have sub-feature sets (middle of cloud), or features (edge of cloud).* - Note - implemented by merging features and feature sets. * *Add support-sets, to make positive assertions about a version supporting a feature-set. Only negative assertions can be made based on features.* - Note - implemented by merging features and feature sets * Drop order of features by feature set. Client will alpha-sort. * *supports.support, drop "prefixed" status. If prefixed, support = 'yes', and prefix is set.* * Add examples of filtering (browser versions in 2010, firefox versions before version X). * Holly's suggestions * Nail down the data, so she has something solid to build a UX on. * sheppy or jms will have experience with how users use tables and contribute to them, how frequently. * Add history resources for specifications, etc. * Add empty resource for deleted items? .. _Resources: resources.html .. _browsers: resources.html#browsers .. _features: resources.html#features .. _sections: resources.html#sections .. _specifications: resources.html#specifications .. _maturities: resources.html#maturities .. _supports: resources.html#supports .. _versions: resources.html#versions .. _changesets: change-control#changesets .. _users: change-control#users .. _history: history.html .. _historical_browsers: history.html#historical-browsers .. _historical_versions: history.html#historical-versions .. _`Browser Compatibility Data Architecture`: https://docs.google.com/document/d/1YF7GJ6kgV5_hx6SJjyrgunqznQU1mKxp5FaLAEzMDl4/edit# .. _CompatGeckoDesktop: https://developer.mozilla.org/en-US/docs/Template:CompatGeckoDesktop .. _CompatGeckoMobile: https://developer.mozilla.org/en-US/docs/Template:CompatGeckoMobile .. _`CSS @font-face at-rule`: https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face#Specifications .. _`Bugzilla 119490`: https://bugzilla.mozilla.org/show_bug.cgi?id=119490 .. _`Bugzilla 1050458`: https://bugzilla.mozilla.org/show_bug.cgi?id=1050458 .. _`availability in Web Workers`: https://bugzilla.mozilla.org/show_bug.cgi?id=996570#c14 .. _`don't localize our brand`: http://www.mozilla.org/en-US/styleguide/communications/translation/#branding .. _`Mapping browsers to 2.2.1 Dictionary Browser Members`: http://lists.w3.org/Archives/Public/public-webplatform-tests/2013OctDec/0007.html .. _`Read a good blog post on the subject`: http://www.troyhunt.com/2014/02/your-api-versioning-is-wrong-which-is.html .. _`Chrome release history`: http://en.wikipedia.org/wiki/Google_Chrome_complete_version_history#Release_history .. _`Firefox release history`: http://en.wikipedia.org/wiki/Firefox_release_history#Release_history .. _`SpecName`: https://developer.mozilla.org/en-US/docs/Template:SpecName .. _`Spec2`: https://developer.mozilla.org/en-US/docs/Template:Spec2 .. _`Google Chrome Release History`: http://en.wikipedia.org/wiki/Google_Chrome#Release_history .. _`Release History of IE`: http://en.wikipedia.org/wiki/Internet_Explorer_1#Release_history_for_desktop_Windows_OS_version .. _`Current Opera version history`: http://www.opera.com/docs/history/ .. _`Presto history`: http://www.opera.com/docs/history/presto/ .. _`Safari version history`: http://en.wikipedia.org/wiki/Safari_version_history#Release_history .. _`Web/API/IDBObjectStore`: https://developer.mozilla.org/en-US/docs/Web/API/IDBObjectStore#Specifications .. _`Web/CSS/:invalid`: https://developer.mozilla.org/en-US/docs/Web/CSS/:invalid#Specifications .. _`Web/CSS/@document`: https://developer.mozilla.org/en-US/docs/Web/CSS/@document#Specifications .. _`Web/CSS/@font-face`: https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face#Specifications .. _`Web/CSS/animation-name`: https://developer.mozilla.org/en-US/docs/Web/CSS/animation-name#Specifications .. _`Web/CSS/border-image-width`: http://developer.mozilla.org/en-US/docs/Web/CSS/border-image-width .. _`Web/CSS/box-decoration-break`: https://developer.mozilla.org/en-US/docs/Web/CSS/box-decoration-break#Specifications .. _`Web/CSS/box-sizing`: https://developer.mozilla.org/en-US/docs/Web/CSS/box-sizing#Specifications .. _`Web/CSS/break-inside`: https://developer.mozilla.org/en-US/docs/Web/CSS/break-inside#Specifications .. _`Web/CSS/caption-side`: https://developer.mozilla.org/en-US/docs/Web/CSS/caption-side#Specifications .. _`Web/CSS/clip`: https://developer.mozilla.org/en-US/docs/Web/CSS/clip#Specifications .. _`Web/CSS/cursor`: https://developer.mozilla.org/en-US/docs/Web/CSS/cursor#Specifications .. _`Web/CSS/display`: https://developer.mozilla.org/en-US/docs/Web/CSS/display#Specifications .. _`Web/CSS/length`: https://developer.mozilla.org/en-US/docs/Web/CSS/length#Browser_compatibility .. _`Web/CSS/line-break`: https://developer.mozilla.org/en-US/docs/Web/CSS/line-break#Specifications .. _`Web/CSS/min-height`: https://developer.mozilla.org/en-US/docs/Web/CSS/min-height#Specifications .. _`Web/CSS/min-width`: https://developer.mozilla.org/en-US/docs/Web/CSS/min-width#Specifications .. _`Web/CSS/outline-color`: https://developer.mozilla.org/en-US/docs/Web/CSS/outline-color#Specifications .. _`Web/CSS/radial-gradient`: https://developer.mozilla.org/en-US/docs/Web/CSS/radial-gradient#Specifications .. _`Web/CSS/ratio`: https://developer.mozilla.org/en-US/docs/Web/CSS/ratio#Specifications .. _`Web/CSS/tab-size`: https://developer.mozilla.org/en-US/docs/Web/CSS/tab-size#Specifications .. _`Web/CSS/text-align`: https://developer.mozilla.org/en-US/docs/Web/CSS/text-align#Specifications .. _`Web/CSS/text-decoration-line`: https://developer.mozilla.org/en-US/docs/Web/CSS/text-decoration-line#Specifications .. _`Web/CSS/text-rendering`: https://developer.mozilla.org/en-US/docs/Web/CSS/text-rendering#Specifications .. _`Web/CSS/text-transform`: https://developer.mozilla.org/en-US/docs/Web/CSS/text-transform#Specifications .. _`Web/CSS/text-underline-position`: https://developer.mozilla.org/en-US/docs/Web/CSS/text-underline-position#Specifications .. _`Web/CSS/transform-origin`: https://developer.mozilla.org/en-US/docs/Web/CSS/transform-origin#Specifications .. _`Web/HTML/Element/Input`: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Input#Browser_compatibility .. _`Web/HTML/Element/address`: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/address#Specifications