Closed Bug 1408494 Opened 7 years ago Closed 6 years ago

Let's show the specification classification on each API

Categories

(Developer Documentation Graveyard :: Add-ons, enhancement, P1)

enhancement

Tracking

(Not tracked)

RESOLVED MOVED

People

(Reporter: andy+bugzilla, Unassigned)

References

Details

An initial specification for browser APIs can be found here:

https://browserext.github.io/browserext/

It would be nice if we could show this on each API that we document on MDN, in addition to showing what browsers it works on.

There'll be some subtelty here because some properties or arguments only work on certain APIs. However we generally say that if you are using "tabs" its on the standards-track. Whereas something like the geckoProfiler is currently Firefox only.

I think we need 4 categories: Firefox only, Experimental, Standards Track and Deprecated.

I outlined why here: https://wiki.mozilla.org/WebExtensions/Spec
Priority: -- → P1
I think we should do this using standard MDN tools rather than build some custom extensions-only thing. In particular, we should:

(1) update the compat data for extensions to include the `status` property: https://github.com/mdn/browser-compat-data/blob/master/compat-data-schema.md#status-information, and

(2) update the Compat macro to show that information in MDN pages.

Let's have (1) as a Q4 content task. I think (2) will be addressed for all MDN reference pages as part of the compat table redesign work.

This does not cover the "Firefox only" category, as described in https://wiki.mozilla.org/WebExtensions/Spec. I'm reluctant to add this kind of thing to MDN pages rather than use the standard tools. I'd tend to think that if some API is "unlikely to ever be copied by any other vendor since it is about a Mozilla specific issue or feature", then perhaps it should not be documented on MDN.
I took a look at the standard API classification fields that MDN offers that Will mentioned and compared them to what Andy proposed on the wiki. Both lists are pretty close.  I think we might be able to use the standard MDN fields to get to the states listed in the Wiki by doing the following:

If Deprecated is TRUE, ignore all other fields.  This API is deprecated.
Else use the value of the Experimental and Standards Track fields to determine API status (using the two MDN fields gives us four states):
	
                      Experimental
                      TRUE  FALSE
Standard Track  TRUE    3      4
               FALSE    1      2

Decoder Ring (maps to the Wiki)
1 = Firefox-only (preliminary API, not part of any proposed standard, likely to change)
2 = Firefox-only (stable API, not recommended as a standard, unlikely to change)
3 = Experimental (recommended as a standard but not part of a track yet, API could change as part of standards process)
4 = Standard (on a standards track or already approved, API unlikely to change)

Most of our current API will land in categories #3 and #4, with a few in #2. An example of #1 is an API that we can only paritally implement in a release, with additional features/functions showing up in later releases (e.g. the tab hiding API being developed for 58).

Will, what do you need to make the Q4 part of Comment 1 happen?
Flags: needinfo?(wbamberg)
> Will, what do you need to make the Q4 part of Comment 1 happen?

Mike, for the first piece (adding the data for WebExtensions), I'll schedule a task for our next sprint to get it done. What's the priority of this, compared with documenting new WebExtension APIs?

For the second piece (rendering spec status in the tables), it's not really in my control, since I'm not working on the compat table redesign.

So let's ask Kadir.
Flags: needinfo?(wbamberg) → needinfo?(a.topal)
We're almost done with the compat table redesign, so it would probably have to be part of the next iteration. I also don't fully understand the mapping and how much work would be involved on our end. Mike, can you mockup an example of what you expect this to look like on a reference page?
Flags: needinfo?(a.topal) → needinfo?(mconca)
I think the model used by the Web API section of MDN is quite good and could be copied by the WebExtensions API section.

https://developer.mozilla.org/en-US/docs/Web/API

Next to each API is a little icon that shows the API status:
  beaker = experimental
  thumbs down = deprecated
  warning triangle = non-standard
  trash can = obsolete
  <blank> = standard

If you click on an API with an icon, there is a banner at the top explaining the status in more detail.  And near the bottom of every API is a Standards section that points to the standard document (if there is one).

I assume all this information is being pulled from the Status property of the compat JSON for the Web API and that MDN has the logic to format things appropriately.  I'd recommend we do exactly the same thing for the WebExtension API, including showing an icon, a header at the top (if needed), and a Standards section (if available).
Flags: needinfo?(mconca)
(In reply to Mike Conca [:mconca] (Denver, CO, USA UTC-6) from comment #5)
> 
> I assume all this information is being pulled from the Status property of
> the compat JSON for the Web API and that MDN has the logic to format things
> appropriately.

No, it's deriving this from tags in the page. It does seem quite broken to be specifying this in two places (the compat data and tags).

> I'd recommend we do exactly the same thing for the
> WebExtension API, including showing an icon, a header at the top (if
> needed), and a Standards section (if available).

What I can do in Q4 is add spec status to all the compat data. The compat table should then be able to render that information (the current beta tables are already doing this, I believe (see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/fontsize#Browser_compatibility if you are a beta tester (https://developer.mozilla.org/en-US/docs/MDN/Contribute/Howto/Be_a_beta_tester)).

What I probably can't do in Q4 is figure out what your requirements are in general for display of this info and implement them. For example, the page you reference (https://developer.mozilla.org/en-US/docs/Web/API) is an alphabetical index of all the web APIs. There isn't an equivalent page for browser extension APIs (the nearest thing is probably https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API or perhaps, at a finer grain, https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Browser_support_for_JavaScript_APIs). So are you asking for a page just like the Web API page? Is there a particular benefit you see in such an index page, or is it just the spec status indication you like? If it's the spec status indicator you like, where do you want them displayed? For example, we could display them in the sidebar, next to the API name. But that again would be extra implementation work in the macros that build the sidebars.

I think there's a major benefit to (1) keeping spec status info in one place, preferably not in page tags and (2) presenting the info consistently across all APIs. These in my mind are good arguments for representing this in the compat tables. I'm not against presenting them in other places, but I would like to do so consistently.
(In reply to Will Bamberg [:wbamberg] from comment #6)
> So are you asking for a page just like
> the Web API page? Is there a particular benefit you see in such an index
> page, or is it just the spec status indication you like? If it's the spec
> status indicator you like, where do you want them displayed? For example, we
> could display them in the sidebar, next to the API name. But that again
> would be extra implementation work in the macros that build the sidebars.

I was going for easy, and was under the (incorrect) assumption that there was already
infrastructure in place to support the kind of layout seen in the Web API section. That
isn't the case, so let's decide what really makes most sense.

> I think there's a major benefit to (1) keeping spec status info in one
> place, preferably not in page tags

Agree 100%.

> and (2) presenting the info consistently across all APIs.

Agree 100%.

> These in my mind are good arguments for representing this
> in the compat tables. I'm not against presenting them in other places, but I
> would like to do so consistently.

I'm totally fine presenting this in the compat tables, I think that makes a lot
of sense. andym and I went through the spreadsheet you put together and I think
we have preliminary classifications for all of the API.
This issue should be tracked in the browser-compat-data repo (https://github.com/mdn/browser-compat-data/issues/618) so I'm closing this bug.
Status: NEW → RESOLVED
Closed: 6 years ago
Resolution: --- → MOVED
You need to log in before you can comment on or make changes to this bug.