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.
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 (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.
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
Comment on attachment 680133 [details] pull request pointer Looks good to me. I added a couple of comments.
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