67
edits
MDN/Archives/Development/CompatibilityTables/Importer: Difference between revisions
Jump to navigation
Jump to search
MDN/Archives/Development/CompatibilityTables/Importer (view source)
Revision as of 14:33, 14 October 2015
, 14 October 2015→Converting MDN Pages to New Tables: Complete first draft of conversion and update instructions
(Starting on instructions for converting MDN pages to new compatibility tables) |
(→Converting MDN Pages to New Tables: Complete first draft of conversion and update instructions) |
||
| Line 109: | Line 109: | ||
If you can't fix an error, contact the MDN writers about it using the {{IRC Full|mdn}} channel on IRC, or on the [[https://lists.mozilla.org/listinfo/dev-mdc dev-mdc mailing list]]. | If you can't fix an error, contact the MDN writers about it using the {{IRC Full|mdn}} channel on IRC, or on the [[https://lists.mozilla.org/listinfo/dev-mdc dev-mdc mailing list]]. | ||
== | == Testing New Tables on MDN Pages == | ||
Starting October 2015, we are converting | Starting October 2015, we are converting some pages to include new compatibility tables generated from API-backed data. These will only be visible to select MDN staff and collaborators. The purpose is to: | ||
* Discover bugs in the importer, API, | * Discover bugs in the importer, API, compatibility tables, and the conversion process, | ||
* Enable MDN staff to make informed decisions on priorities and deliverables, and | * Enable MDN staff to make informed decisions on priorities and deliverables, and | ||
* Define and deploy the features needed to open the new tables to beta users. | * Define and deploy the features needed to open the new tables to beta users. | ||
We are explicitly deferring some features (such as non-English variants, scaling for production, and client-side refreshes) while the basic functionality is tested and improved. We are only converting a handful of pages, since editing will be buggy and difficult for months, and converted pages may need to be manually processed due to design changes. | |||
=== Prerequisites === | === Prerequisites === | ||
| Line 121: | Line 123: | ||
# Sign into [https://developer.mozilla.org/en-US/ MDN] (Anonymous users get the old compatibility tables) | # Sign into [https://developer.mozilla.org/en-US/ MDN] (Anonymous users get the old compatibility tables) | ||
# Go to the [https://developer.mozilla.org/en-US/docs/Web/CSS/background#Browser_compatibility Browser Compatibility section of Web/CSS/background]. If you see the new table (green and red boxes, icon headers), then you are in testing group on MDN. | # Go to the [https://developer.mozilla.org/en-US/docs/Web/CSS/background#Browser_compatibility Browser Compatibility section of Web/CSS/background]. If you see the new table (green and red boxes, icon headers), then you are in the testing group on MDN. | ||
# Sign into the [https://browsercompat.herokuapp.com BrowserCompat website] | # Sign into the [https://browsercompat.herokuapp.com BrowserCompat website] | ||
# Go to the [https://browsercompat.herokuapp.com/importer/651 importer page for /Web/CSS/background]. If there is a "Commit" button under actions, you have the | # Go to the [https://browsercompat.herokuapp.com/importer/651 importer page for /Web/CSS/background]. If there is a "Commit" button under actions, you have the <code>import-mdn</code> permission needed to convert an MDN page. | ||
If you want to be part of the testing group, the #browsercompat [https://wiki.mozilla.org/Irc IRC channel] is a good place to start the discussion. | |||
=== Identifying a Converted Page === | |||
Here are the components of a converted MDN page, using [https://developer.mozilla.org/en-US/docs/Web/CSS/background#Browser_compatibility Web/CSS/Background] as an example: | |||
# The page appears in [https://developer.mozilla.org/en-US/search?locale=%2A&kumascript_macros=EmbedCompatTable search results for the EmbedCompatTable macro] | |||
# The BrowserCompat [http://browsercompat.herokuapp.com/importer/651 importer page] shows no errors (some warnings are permitted). | |||
# The imported data has been committed to the API, which can be confirmed by following the "Feature ID" link at the top of the page ([http://browsercompat.herokuapp.com/view_feature/655 655] for Web/CSS/Background). A committed feature will show Specifications and Browser compatibility data, similar to the importer page. An [http://browsercompat.herokuapp.com/view_feature/656 un-committed feature] will show no data. | |||
# The [https://developer.mozilla.org/en-US/docs/Web/CSS/background?raw#Browser_compatibility source of the MDN page] has a <code><nowiki>{{CompatibilityTable}}</nowiki></code> macro, HTML tables, and an <code><nowiki>{{EmbedCompatTable("slug")}}</nowiki></code> macro. | |||
# When logged in as a test user, [https://developer.mozilla.org/en-US/docs/Web/CSS/background#Browser_compatibility the new API-backed table is displayed], including color-coded support information, icons for browsers, and a legend. | |||
# When visiting as an anonymous user (such as browsing in private mode or an alternate browser), the traditional MDN compatibility table is displayed. | |||
=== Convert an MDN Page === | === Convert an MDN Page === | ||
''to | |||
# Find a suitable MDN page. It should import with no errors, have good compatibility data and footnotes, and describe an older technology that isn't expected to change much in the next 6 months. | |||
# If you haven't already, sign into the [https://browsercompat.herokuapp.com BrowserCompat website]. | |||
# [http://browsercompat.herokuapp.com/importer/ Find the importer page] for the MDN page. You can paste the URL in the search box to find it directly, or use the [http://browsercompat.herokuapp.com/importer/?topic=docs%2FWeb%2FCSS Topic filters] and browse the page list. You may want to bookmark the page or write down the importer ID for future reference. | |||
# On the importer page in the Actions section, click the "Reset" button to download and parse the latest page. | |||
# Look for import errors or problems with the compatibility data. If needed, fix the MDN page, and click "Reset" again, repeating until issues are resolved. | |||
# In the Actions section, click the "Commit" button to add the parsed data to the API. | |||
# In the Raw Data section, take note of the API <code>id</code> and the <code>slug</code>. | |||
# On the MDN page, edit the page and scroll the to Browser Compatibility section. Add a <code><nowiki>{{EmbedCompatTable("slug")}}</nowiki></code> macro (replacing <code>"slug"</code> with the quoted slug from the importer page) just before the next section (usually <code><h2>See also<h2></code>), after the compatibility tables and any footnotes. Do '''not''' remove the <code><nowiki>{{CompatibilityTable}}</nowiki></code> macro at the top of the section, which is needed for the traditional display. | |||
# Save the page, and refresh until the new page is rendered. | |||
=== Update Compatibility Data on a Converted Page === | === Update Compatibility Data on a Converted Page === | ||
# Edit the compatibility data in the traditional tables on the MDN page, and save your changes. This will update the traditional tables, but the API-backed tables will show the old data. | |||
# Sign into the [https://browsercompat.herokuapp.com BrowserCompat website]. | |||
# [http://browsercompat.herokuapp.com/importer/ Find the importer page] for the MDN page. | |||
# On the importer page in the Actions section, click the "Reset" button to download and parse the updated page. | |||
# Look for import errors or problems with the compatibility data. If needed, fix the MDN page, and click "Reset" again, repeating until issues are resolved. | |||
# In the Actions section, click the "Commit" button to update the API with the new data. | |||
# Return to the MDN page and [http://www.wikihow.com/Force-Refresh-in-Your-Internet-Browser force refresh] the page to re-run the macros | |||
# Wait until the new page, with updated API data, is rendered. | |||
== The Issues == | == The Issues == | ||