Re: On deploying next release of compatibility tables

Almost there!

Good news! The code has been updated on the whole stack and accessible
in the test wiki.

*WARNING* This is a big email, sorry for that, but a lot to report.

TL;DR, if nobody finds a problem, i have the intention to deploy on the
live wiki by Monday 14 july.


What we have:
- MediaWiki extension reads the new format
- data.json JSON file structure had been validated with Doug
- mdn-compat-importer ran one last time and is published at [1][2]
- The test wiki has refreshed examples


Read on if you want to have review what i’ve done.



## The new format

Like described at [5] we were losing data. For example the compat data
about the script tag existed in both HTML and SVG. After some digging,
there were not that much loss (about 20 properties) but it made us
re-consider the format and make sure we do not lose anything.

From:

    {data: {script: {contents: {mobile: {}, desktop:{}}}}}

To:

    {data: {
      html: {
        script: {contents: {mobile: {}, desktop: {}}}
      },
      css: {},
      svg: {
        script: {contents: {mobile: {}, desktop: {}}}
      },
     },
     duplicates: [],
     folders: [
       "css",
       "html",
       "svg"
     ]
    }

Note that there are more folders, see at the bottom of [2], but you see
that we won’t loose data anymore.

We do have some in ducplidates, but we’ll keep them there for now. After
some review we realized that the ones in duplicates are there only
because the scraper wasn’t removing pages with different URIs (e.g.
"Casing" vs "casing", or "folder/" vs "folder")  but the same content.


### New properties in the data.json file

In the new format, I added two properties:
- breadcrumb
- jsonselect

Both are useful if you want to search a particular part of the big file
from the web browser.

Breadcrumb was useful for me know in which folder i’d sort it.

The jsonselect element is useful if you want to use underscore-cli
(Underscore JS for the terminal) and query the data.

See jsonselect.org [5] and underscore-cli [6], an example of use is
given at [7]



## Review the generated table with hardcoded tag

If you go to a page in the test wiki [0], you can see and play around to
add compatibility tables in the content.

To do so, add a tag:

    <compatability feature="css/border-radius"
format="table"></compatability>

To see where the data comes from you can look for

    .css > .border-radius

In both the raw file [1] or the human friendly file [2]



## See how a topic page gets the table generated

In a situation where we know a page will be related to a specific topic
(e.g. CSS), we can have the table generated without having to include
the tag manually.

In fact, in some cases we can do that.

For example, the border-radius CSS property is at
/wiki/css/border-radius and our JSON data [4][5] file will then look in
data['css']['border-radius'].

This is done through the Template:CSS_Property [8] template that is
included in most CSS pages.

Soon enough, we might have to allow us to add our own data entry because
pages such as [4] (at "/css/selectors/pseudo-classes/:active") will not
find automatically the data in the JSON file at  .css > .pseudo-active


  [0]:
http://docs.webplatform.org/test/Tests/Compatibility_table_and_caching
  [1]:http://docs.webplatform.org/compat/data.json
  [2]: http://docs.webplatform.org/compat/data-human.json
  [3]:http://docs.webplatform.org/test/css/properties/border-radius
  [4]:
http://docs.webplatform.org/test/css/selectors/pseudo-classes/:active#Compatibility_table_example
  [5]: http://jsonselect.org/
  [6]: https://github.com/ddopson/underscore-cli
  [7]:
http://docs.webplatform.org/wiki/WPD:Projects/CompaTables/Reading_the_data.json_file
  [8]: http://docs.webplatform.local/test/Template:CSS_Property
  [9]:
http://lists.w3.org/Archives/Public/public-webplatform/2014Jul/0033.html


-- 
Regards,

Renoir Boulanger  |  Developer operations engineer
W3C  |  Web Platform Project

http://w3.org/people/#renoirb  ✪  https://renoirboulanger.com/  ✪  @renoirb
~