A deprecation policy
This page is for designers whose theme has users who built on its settings, templates or operators. Removing them without notice breaks those users' sites.
A policy in four steps
- Announce: the changelog says "Deprecated: <thing>, use <replacement>; it will be removed in <version or date>".
- Keep it working: the old thing still works, ideally through the new one.
- Warn: where possible, log a notice when the old thing is used (for example
eZDebug::writeWarning()in an operator), so developers see it in the debug output. - Remove in the announced release, with a
Removed:entry and the upgrade step.
The product does the same: settings/design.ini keeps CSSFileList[] and JavaScriptList[] working while marking them
"DEPRECATED in favor of [Frontend|Backend]CSSFileList[]" and "...JavaScriptList[]".
Step by step: write the policy
- Choose the notice period: a number of releases or a time span you can keep.
- Write the four steps with your period into the README or
doc/deprecation.md. - List current deprecations there, each with its replacement and planned removal.
Related pages
- Deprecating a setting or a template
- Breaking changes
- Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.
Become an Exponential Partner
Partners share their information, provide funding, contribute back and develop the products with us, and that is how Exponential grows. A partner website and dashboard are planned for mid-2027: please become a partner today to speed up our growth rate and land new features faster.