Note: There are a few cases of duplicates in user autocompletion which are being worked on.

Define our module stability ratings in the SDK docs



Add-on SDK
5 years ago
5 years ago


(Reporter: wbamberg, Assigned: wbamberg)


Firefox Tracking Flags

(Not tracked)



(1 attachment)



5 years ago
We're intending to use the module stability ratings that are defined for node.js (

In the SDK docs, we should have a page explaining this, and pointing at the full process on the Wiki.


5 years ago
Priority: -- → P1

Comment 1

5 years ago
Created attachment 680133 [details]
pull request pointer

Here's a pull request that:

* adds a new page explaining module stability and deprecation, culled from the blog post ( and Wiki page (

* reads the module metadata to get the stability rating of each module and inserts a little banner at the top of each module doc page with the corresponding text in an appropriate colour, which links to the new page

There are a few things worth worrying about IMO.

(1) The stability ratings assigned to modules aren't all what I'd expect:

* these modules don't contain any metadata:

* we sort of agreed (I thought) that we'd not use "unstable", (using only "experimental", "stable", and "deprecated") but many modules use it. I think these should be changed to "experimental".

* "sdk/timers" is deprecated. Really? (Aside: it's hard to see when changes like this got introduced, because it looks as if the layout reorg loses all the file history in GitHub. Can that really be true??)

I'd suggest we raise a bug to get these right, once and for all. And also to add a test to check that each module contains a valid value for "stability".

(2) The way I'm getting the module metadata out of the JS files is not very reliable: there are many ways the metadata could be written that would break it. But *reliably* getting the module metadata, which is defined as a JS variable out of the files using Python seems to me a very hard problem, especially if we want to minimise our external dependencies. I think my implementation is very simple, reasonably fast, and probably "good enough", but if you have any other ideas I'd be very glad to hear them.

(3) I've chosen to display the stability values at the top of each module's doc file, in a coloured box. I've chosen green, yellow, red for "stable", "experimental" and "deprecated", which seems to map quite nicely on to "use", "use with caution", and "do not use". But I'm no graphic designer, and would happily accept input on this. I'm also happy to ship this as a first effort, and implement any improvements anyone else can suggest when they see it.

I thought the top of the page started to look quite cluttered with this and the search bar, so I've removed those links to DevHub and Builder, that I think we discussed. But if you think I should reinstate them I can do that.
Attachment #680133 - Flags: review?(dtownsend+bugmail)
Attachment #680133 - Flags: feedback?(zer0)

Comment 2

5 years ago
At least, I think, the text ought to be white in the "deprecated" box.
Comment on attachment 680133 [details]
pull request pointer

A few comments in the pull request but otherwise looks good
Attachment #680133 - Flags: review?(dtownsend+bugmail) → review+
Comment on attachment 680133 [details]
pull request pointer

Looks good to me. I added a couple of comments.
Attachment #680133 - Flags: feedback?(zer0) → feedback+


5 years ago
Depends on: 811960

Comment 5

5 years ago
Commit pushed to master at
Merge pull request #654 from wbamberg/786286

Fix for bug 786286 - Define our module stability ratings in the SDK docs


5 years ago
Last Resolved: 5 years ago
Resolution: --- → FIXED
You need to log in before you can comment on or make changes to this bug.