SDK private-browsing API deprecation

If you’ve looked through the documentation for Add-on SDK 1.11, you may have noticed that the page documenting the private-browsing module contains the following message:

The activate and deactivate methods are now deprecated. They will continue to work until version 1.13 of the SDK. From version 1.13 onwards they will still exist but will have no effect when called.

While the Jetpack project has often in the past declared a goal of maintaining forward-compatibility of high-level apis. I feel strongly that we should whenever possible maintain api compatibility so that add-on developers can depend on the SDK’s apis to work even as months go by and any number of new Firefox versions are released into the wilds of the web.

Sometimes the issue of backwards compatibility is out of our hands and changes to Firefox necessitate that we change high-level apis in the SDFK in order to keep pace. The current work on implementing per-window private browsing in Firefox is just such an issue, and as such we’ve taken steps in the recently released SDK 1.11 to print deprecation warnings for the ‘activate’ and ‘deactivate’ methods in the SDK’s private-browsing module to the error log.

For the time being these methods will continue to work, but per-window private browsing ( PWPB for short ) is a new set to debut in Firefox 20 (or so) that fundamentally changes how Firefox behaves. The new implementation breaks the assumptions that the SDK’s private browsing module makes about what is possible, so we have taken steps to deprecate parts of this module. To be specific, the ‘activate’ and ‘deactivate’ methods in the private-browsing module now produce deprecation warnings:

Timestamp: 2012-11-05 1:39:42 PM
Error: pb-deprecation-example: DEPRECATED: require("private-browsing").activate 
and require("private-browsing").deactivate is deprecated.

Here’s an example of code that will trigger this behaviour:

var pb = require("private-browsing");

require("widget").Widget({
    id: 'pb-foo',
	label: 'PB, TOGGLE!',
	contentURL: 'http://www.mozilla.org/favicon.ico',
	onClick: function() {
        if (pb.isActive) {
            pb.deactivate();
        }
        else {
            pb.activate();   
        }
	}
});

To easily try this out, please see this builder example.

We expect to ship per-window private browsing in Firefox 20, and once Firefox no longer supports the old private browsing mode any calls to the deprecated methods in the private-browsing module will have no effect. If your add-on uses these apis, you should look instead at bug 808747 which will track how we support per-window private browsing.

4 responses

  1. Fred wrote on :

    Hm, not sure what to think about deprecating an API with no way to update my app to the “new” preferred way. Will you blog again how to ideally handle this situation when the new API will be available? Presumably, there will be a way to do feature detection?

    1. Jeff Griffiths wrote on :

      That’s an interesting point, I can see a need for some indication from our module as to whether per-window private browsing is implemented or not. What would you think of:

      var hasPWPB = require('private-browsing').hasPerWindowPrivateBrowsing || false;
      

      We could implement this for 1.12 perhaps and test for a specific version of Firefox?

      1. Fred wrote on :

        That works or of course if the old API will in fact error out at some point, you can detect it that way (alternatively, checking for the *new* API to be present vs. not present might be enough, if that’s even possible).

        Thanks for filing the bug!

    2. Jeff Griffiths wrote on :

      I’ve logged a bug to track this:

      https://bugzilla.mozilla.org/show_bug.cgi?id=809180