Identity at Mozilla

Home of the Mozilla Identity team

  1. Committing to a Stable API for Persona

    Sep 17, 2012 — by callahad

    Later this month, we will be announcing the first “beta” release of Persona. Part of that announcement will include committing to long-term support for our APIs, so that developers can more confidently rely on Persona in their sites and applications. This post will serve to outline the deprecation strategy that Persona will adopt for its beta releases.

    How is deprecation handled?

    Before deprecating or making backwards incompatible changes to stable APIs, the Persona team will announce the change on the Persona-notices mailing list. The team will also add deprecation warnings to the relevant code and documentation.

    The notice will be posted at least six months prior to the change taking effect. After posting the notice, the team will listen for feedback and monitor the ongoing use of the API. Depending on these metrics, the deadline may be extended once by an additional six months. Any extension will be communicated via the Persona-notices mailing list.

    Can changes happen more quickly?

    Yes. If a security vulnerability necessitates a backwards incompatible change to a stable API, then that change may be expedited and a message will be sent to Persona-notices.

    Backwards compatible and cosmetic changes may also be expedited.

    What APIs are covered?

    Beta 1 will only stabilize the subset of Persona APIs that are necessary for authenticating users. Subsequent beta releases will eventually extend this commitment to the remaining APIs, Persona’s data formats, and the cross-browser shim.

    Specifically, the first beta release will only commit to:

    1. id.watch() and its loggedInUser, onlogin, and onlogout options.
    2. id.logout() without any parameters.
    3. id.request() with its oncancel, privacyPolicy, termsOfService, returnTo, siteName, and siteLogo options.
    4. id.get() with its privacyPolicy, termsOfService, siteName, and siteLogo options.

    What about APIs that are already deprecated?

    APIs that are undocumented or already marked as deprecated may be removed more rapidly. This includes:

    1. id.getVerifiedEmail().
    2. The loggedInEmail and onready options for id.watch().
    3. The privacyURL and tosURL options for id.request().
    4. id.logout() when passed a callback as its first parameter.
    5. The requiredEmail, silent, privacyURL, and tosURL options for id.get().

    If you are using any of these undocumented or deprecated APIs, please update your code. As per usual, backwards incompatible deprecations will be announced on the Persona-notices mailing list in advance.

    What resources are available to help with upgrades?

    While the APIs are fully documented on MDN, the Persona team is committed to supporting developers that rely on Persona.

    If you have questions regarding upgrading your code in response to a deprecation notice, please contact us via the dev-identity mailing list or stop by our IRC channel: #identity on irc.mozilla.org.

    Lastly, if your site depends on Persona, or you are supporting people who do, please subscribe to the Persona-notices mailing list.