From:  Jean-Yves Perrier <jypenator@gmail.com>
Date:  31 Mar 2017 18:14:38 Hong Kong Time
Newsgroup:  news.mozilla.org/mozilla.dev.mdc
Subject:  

Re: Review of browser compat schema

NNTP-Posting-Host:  63.245.214.181

Hi!

We are close to a version 1.0.0 of the schema, the last step is to 
actually use it in a macro.

The original links have been updated with the latest version.

My answer to the feedback:


On 16/03/2017 20:05, Stephanie Hobson wrote:
> Hey,
> 
> 
> Flags and flag values must be in machine readable format like prefixes and
> alternative names. One of my highest priorities here is visually displaying
> the same information caniuse does. We can't do that if that information is
> contained in a string. With the current schema it is not possible to show
> an icon in an interface if feature is behind a flag. I consider this
> essential.

I've added it:



> 
> I think it would be useful to reverse all the browser identifiers so that
> when sorted alphabetically related products are next to each other - or the
> schema could define and enforce a standard order. This will make it easier
> to write code to consume the API that can handle additions of new browsers
> (or non-browsers like node). mobile_ie would become ie_mobile.
> android_firefox would become firefox_android.
Done!

> 
> I don't see a way to encode partial support or to encode no support
> associated with a version number (so a note could be added). For example,
> how would we handle the fact that IE 10 &11 implement an older version of
> the grid layout spec with the -ms- prefix? Also, since we consider a
> feature behind a flag to be unsupported, how would we add a support entry
> showing that starting in version X this feature is behind a flag (it seems
> like the current schema would require us to say version: false).

This one is a good point!

I've added a boolean flag ("partial_implementation") for a case where 
the implementation is not really interoperable (like implementing an old 
version of the spec). I've recommended to add a note to explain howthis 
implementqtion is problemeantic.

And yes "version_added": false, "notes": "blabla" is the way to add a 
not in case of a non existing version.

> 
> I disagree with making any browser support information mandatory. Missing
> information will be handled as version: null whether we make someone type
> it in or not. I disagree especially with making android_firefox mandatory,
> there isn't the market share to support this and we want our resource to be
> seen as browser agnostic.

Fixed, no browser is mandatory.


> 
> I was confused by the difference between the simple and advanced support
> options when I read the first few paragraphs. The following paragraphs made
> it much clear-er how it works and I think this is a good system but I think
> the first section needs to be reworded.

I fixed it by explaining the array of support of options, and explaining 
that if there is only one suppport objects, the array is optional.


> 
> The descriptive text around the "notes" string is confusing. The text says
> to use the string to give the sub feature a title but the example shows a
> description of detailed support information and the "notes" object is only
> valid in a support statement. The title for the sub feature should be
> attached to the subfeature object, but there's already a "desc" field there
> that seems to fill that role. I'm confused.

Fixed, it was a bad cut & paste.

> 
> The spacing in your examples is pretty wonky in GitHub's webview. We should
> probably define a number of spaces to use and publish that. Maybe an
> .editorconfig file. (4 spaces is the Mozilla Web Dev standard, I like that
> a lot)
Fixed.

Additional feedback from a live session in Toronto:

On 22/03/2017 16:35, Stephanie Hobson wrote:
> - support and support too confusing
>     - change basic support to basic support
Done. "basic_support" is the only required subfeatures (it was called 
'support' beforehands.

> - version and end_version:
>     - need to name them to be clear
>     - need to consistant name
>     - version_first, version_last ?
version_added
version_removed

> - both versions and notes should handle arrays or a single value
>     - change notes to handle single values
Done. I've updated the docs too to say the array one is the standard 
way, but that if there is only one, the array can be ommitted. I think 
it is an easier description than using simple_syntax and array_syntax 
and explaining it is an alternative.

> - clarify names of status properties
>     - experimental, standardzied, etc.
>     - differences between them are too confusing
So I have:
- kept experimental, but removed stable. It is either experiment or 
stable not both. If we find an edge case, we can reintroduce stable 
later, but I prefer not to have to deal with guaranteeing the 
consistency between both for 99% of the cases
- renamed standardized to 'standard_track'

> - allow slugs for anything but list the 12 browsers?

Done. This add flexibility, but makes review important: typo will not be 
catched by the automatic validation process.

-- 
Jean-Yves Perrier
Senior St. Project Manager, Developer Documentation / MDN