Jetpack/Module Deprecation Process

	THIS PAGE IS A WORKING DRAFT
	The page may be difficult to navigate, and some information on its subject might be incomplete and/or evolving rapidly. If you have any questions or ideas, please add them as a new topic on the discussion page.

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
• AMO validator will throw errors when deprecated modules are used, and these add-ons will therefore fail AMO review

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.