Jetpack/Module Deprecation Process

Preparation

Before deprecating a module, we need to:

• decide we want to deprecate it
• develop and document an alternative
• decide which release we want to deprecate it in

(Should we have some sort of pre-deprecation announcement/consultation?)

Deprecation

In the chosen release, communicate the module's deprecation:

• update the module's metadata to be "deprecated"
• include a deprecation notice in the release notes, AMO blog, mailing list. The deprecation notice should point developers at a migration guide.

Migration

During the deprecation period (default 18 weeks), the module will be in the deprecated state.

Support

We will track usage of deprecated modules on AMO and support developers migrating their code.

(Should we do more targeted outreach, especially for non-AMO add-ons?)

Warnings

We will continue to provide warnings (will these happen automatically driven by the metadata?):

• CFX will generate warnings when developers use deprecated modules
• API documentation will warn users about that the module is deprecated, which release is expected to remove it, and how to migrate
• Attempts to use a deprecated module at runtime will log an error to the error console
• AMO validator will throw errors when deprecated modules are used, and these add-ons will therefore fail AMO review

All warnings should include links to further information about what to use instead of the deprecated module and when the module will be completely removed.

Removal

The target removal date is 18 weeks after deprecation. In preparation for this date we'll decide whether we're happy to go ahead with removal: this will depend on how many users have successfully migrated from the deprecated module.

OK to remove

If we're happy to remove the module, we'll remove it and relocate it to a graveyard repository (URL?).

We'll remove the corresponding documentation, and communicate the removal in the usual ways:

• release notes
• AMO blog
• mailing list

Not OK to remove

If we're not happy with removal, we'll continue to support migration and target the next release.