This document outlines Sensei’s code deprecation policy, how internal code is marked, and the timelines for removing deprecated code from the codebase.
Deprecated code is always removed in a major release. The scenarios below assume that there is at least one minor release that contains the deprecation before the major release in which the code is removed.
When to Remove Deprecated Code
Deprecated code removal will adhere to the following guidelines:
- Code that is considered public will be removed two major versions after the deprecation. This includes hooks, public and protected methods and global functions that have not been marked with
- Functions and methods marked with
@access privateare considered private and shouldn’t be used. They will be removed in the next major version after being marked as deprecated.
Internal code is considered “not-for-public-use” and is meant to be part of Sensei core. This code might change in future releases without being deprecated first. In other words, backward compatibility of internal code is not guaranteed.
- Code in the
Sensei\Internalnamespace or marked with
@internalis considered part of the core and may change without notice.
- Code marked with
@experimentalis part of an experimental feature that could have a major overhaul in the near future.
- Private methods may be removed without notice.
- Public class constants are considered private and may be removed without notice.
Code Deprecation Process
When deprecating code, the scenarios above can be used to arrive at the major version in which the code will be removed and, if desired, the version can be included in the deprecation notice. Code will be marked as deprecated by using standard WordPress methods for this purpose
A Github issue for tracking deprecations should be created and attached to the appropriate milestone. A reference to the pull request in which the code was deprecated, and the name of the function/method/hook that is being deprecated, should be added to the issue description. Additional deprecations scheduled for removal in the same release can be appended to the existing issue.