Code Deprecation

Diamonds are forever, not always the case when it comes to code though. Here are some tips to help ensure a smooth and error free transition when removing or changing APIs.

Things to watch out for

• Other plugins and themes may be relying on the code you’re about to remove, so we can’t just do that. A good way to gauge the use of a function or a class can be to search for it in OpenGrok and WPDirectory.
• Deleting a file that was loaded and in use in the previous release can cause fatal errors on sites with aggressive OpCache setups.

Steps for smooth deprecation

1. Use WordPress’ deprecation functions to mark your code as deprecated while retaining its current functionality.
   • _deprecated_file()
   • _deprecated_hook()
   • _deprecated_class()
   • _deprecated_constructor()
   • _deprecated_function()
   • _deprecated_argument()
2. Once deprecated, the API needs to remain in Jetpack for 6 months, so third-parties have time to find out about the deprecations and update their codebase.
3. If possible, reach out to partners who rely on the deprecated code to let them know when it will be removed, and how they can update.
4. If necessary, publish an update guide on developer.jetpack.com.

Example

/**
 * This is an example function about to be deprecated.
 *
 * @deprecated $$next-version$$ This function is deprecated. Please use other_example_function() instead.
 *
 * @return string
 */
function example_function() {
    _deprecated_function( __FUNCTION__, '{plugin/package}-$$next-version$$' );

    return 'example'
}

Note: $$next-version$$ placeholder will be automatically updated with the correct version number at the time of the next release. Read more about it here.