Review of browser compat schema

[Jean-Yves Perrier]

Hi all!

I have put together the feedback I got from you on a new browser compat
schema.


Here it is! I've not yet merged it to the main repository (as plenty of
existing browser compat data needs to be updated, as well as our macros).

So you'll find:

1. The documentation of the schema:
https://github.com/teoli2003/browser-compat-data/blob/schema-with-identifier/compat-data-schema.md

2. The schema itself:
https://github.com/teoli2003/browser-compat-data/blob/schema-with-identifier/compat-data.schema.json

3. A few examples:

- background-position-x
[https://github.com/teoli2003/browser-compat-data/blob/schema-with-identifier/css/properties/background-position-x.json
]

- background
[https://github.com/teoli2003/browser-compat-data/blob/schema-with-identifier/css/properties/background.json
]

- text-align-last
[https://github.com/teoli2003/browser-compat-data/blob/schema-with-identifier/css/properties/text-align-last.json
]

- :any-link
[https://github.com/teoli2003/browser-compat-data/blob/schema-with-identifier/css/pseudo-classes/any-link.json
]


What are the next steps:

1. A last round of feedback (now), and incorportate it

2. Creation of the prototype: that is a macro that use the JSON format
to display compat data

3. Define actions needed to go from the prototype to a product-grade
system (like correct integration of json file in kumascript macros, l10n
set-up, updating existing data and macros)


I'm really happy about it, and I hope I have not oversighted some of
your previous feedback. Thank you for the help.


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

[Chris Mills]

Awesome work, Jean-Yves. You supremely rock.

Chris Mills
Senior tech writer || Mozilla
developer.mozilla.org || MDN
cmi...@mozilla.com || @chrisdavidmills

> _______________________________________________
> dev-mdc mailing list
> dev...@lists.mozilla.org
> https://lists.mozilla.org/listinfo/dev-mdc
> MDN contributor guide: http://bit.ly/ContributorGuide

[Stephanie Hobson]

Hey,

I'm sorry to be only providing feedback so late in the process, especially
if I am bringing up stuff that has been discussed in detail. (7 weeks off
will do that!) Here are my thoughts:

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 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.

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).

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.

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.

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.

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)

I am excited to see this getting closed to finished and ready! That's a lot
of forward movement in my time away :)

Thanks,
Stephanie.




On Wed, Mar 15, 2017 at 7:41 AM, Jean-Yves Perrier <jype...@gmail.com>

[Jean-Yves Perrier]

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.

[Sebastian Zartner]

Hi all,

Stephani was obviously still early with her feedback in comparison to me.
I'm very sorry for that! I'm just too busy lately.

On 31 March 2017 at 12:14, Jean-Yves Perrier <jype...@gmail.com> wrote:

> 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:
>
>> 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.
>

The :any-link example still uses tabs instead of spaces.

> 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.
>

Please see https://groups.google.com/forum/#!searchin/mozilla.dev.
mdc/basic%7Csort:date/mozilla.dev.mdc/vNDUwR1x71g/BXu550X9AAAJ
<https://groups.google.com/forum/#%21searchin/mozilla.dev.mdc/basic%7Csort:date/mozilla.dev.mdc/vNDUwR1x71g/BXu550X9AAAJ>,
where I asked whether 'basic support' is mandatory in regard of the
fit-content() [https://developer.mozilla.org/en-US/docs/Web/CSS/fit-content]
function (see also https://bugzil.la/1318882#c4).

- 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'
>

Why not just 'standard'?

And what about a feature that got removed from the standards and also from
implementations? Should it be removed completely or should we add a new
status for that case? (On MDN we differenciate this by 'deprecated' and
'obsolete'.)

Other feedback:

Didn't we decide to split the different categories and maybe even features
into different files?

Sebastian