786286 - Define our module stability ratings in the SDK docs

Status: RESOLVED FIXED

(Add-on SDK Graveyard :: Documentation, defect, P1)

Description

[Will Bamberg [:wbamberg]]

We're intending to use the module stability ratings that are defined for node.js (https://gist.github.com/1776425).

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

Comment 1

[Will Bamberg [:wbamberg]]

Attachment: pull request pointer

Here's a pull request that:

* adds a new page explaining module stability and deprecation, culled from the blog post (https://blog.mozilla.org/addons/2012/10/01/a-lifecycle-for-the-add-on-sdks-apis/) and Wiki page (https://wiki.mozilla.org/Jetpack/Module_Deprecation_Process)

* 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:
self
content/content-proxy
net/url
test/harness
test/runner
util/list

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

Comment 2

[Will Bamberg [:wbamberg]]

At least, I think, the text ought to be white in the "deprecated" box.

Comment 3

[Dave Townsend [:mossop]]

Comment on attachment 680133 [details]
pull request pointer

A few comments in the pull request but otherwise looks good

Comment 4

[Matteo Ferretti [:zer0] [:matteo]]

Comment on attachment 680133 [details]
pull request pointer

Looks good to me. I added a couple of comments.

Comment 5

[[github robot]]

Commit pushed to master at https://github.com/mozilla/addon-sdk

https://github.com/mozilla/addon-sdk/commit/da566f75ddd26fd06c10ef0187a879d571d41073
Merge pull request #654 from wbamberg/786286

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