Current state of deprecation
Right now, our deprecation policy basically states that:
- Deprecations only happen on master
- A minimum of four versions must happen between the initial deprecation and the 'final' deprecation
- The deprecation policy applies to all public APIs, classes, and files
The description for the initial deprecation basically states that when marking as deprecated, where possible the functionality should continue to work, and a debugging message should be output.
The description for the final deprecation basically states that when something is finally deprecated, then the content of the function should be replaced with an exception.
I would like to propose two things:
- rather than hard tying deprecation to a four-version rule between the initial and final deprecation, we should link deprecations to the LTS release policy; and
- we should change the final release to mean actual removal of the deprecated content, rather than conversion to an Exception.
What does this mean
We've had a long term support release in Moodle for a number of years. This LTS release is used for several things, including:
- as a required minimum when performing upgrades (in order to upgrade to Moodle 3.9 LTS you have to already be running at the Moodle 3.5 LTS or higher); and
- to link our minimum and maximum PHP versions to the LTS (The minimum supported version of PHP for the 3.9 LTS is a version of PHP supported in the 3.5 LTS).
Both of these things are related to deprecations - for our upgrades we need to ensure that deprecated classes, functions, etc. are not used in any way.
Linking final deprecation to the LTS
Starting to link the deprecation period from a rolling period to a fix point in time means that all final deprecations can take place at the same time. It also means that old APIs are guaranteed to exist for a consistent period too.
The idea is that the when a deprecation occurs, the old functionality will, where possible, continue to work until after the release of the next LTS version.
For example, if a function is deprecated in Moodle 3.8, then that function should continue to work until after the next LTS has been released.
There are currently two proposals:
Proposal B: Removal will take place in the release immediately after an LTS:
- Deprecation in 3.1 (LTS), 3.2, 3.3, 3.4 => Removal in release after 3.5 (LTS) => Removal in 3.6
- Deprecation in 3.5 (LTS), 3.6, 3.7, 3.8 => Removal in release after 3.9 (LTS) => Removal in 4.0.
The minimum amount of time for a final removal is 1.0 year, and the maximum is 2.5 years.
The rationale of the shorter deprecation policy here is that if you are a developer working primarily with LTS releases, you will not be affected. If you are a developer working with clients who use the interim releases, then you will likely be addressing the deprecations as soon as you encounter them. You are unlikely to be affected by the shorter period in either case.
Proposal C: Removal will take place in the release immediately before the following LTS.
- Deprecation in 3.1 (LTS), 3.2, 3.3, 3.4 => Removal in release before 3.9 (LTS) => Removal in 3.8
- Deprecation in 3.5 (LTS), 3.6, 3.7, 3.8 => Removal in release before 4.3 (LTS) => Removal in 4.2
The minimum amount of time for a final removal is 2.0 years, the maximum is 3.5 years.
The rationale of the longer period comes from a concern about switching to a shorter period.
Changing the meaning of final deprecation
The second part of the proposal is to change the final deprecation to mean removal of the function entirely rather than conversion to an exception.
This means that we can start to kill off old code which has been sitting around for many years. We still have deprecated functions which were deprecated prior to Moodle 1.5 for example. These serve no real benefit. These deprecations are also mentioned in an upgrade.txt and have been warned about for several releases before the final removal stage anyway.
This part is really just a house-keeping process.
What might this mean for me?
For the most part the hope is that this will make developer lives easier as LTS releases will be more of a focal point in the deprecation process. Otherwise there should be little change to developers.
What do you want from me?
I would really love to hear feedback on both of the proposed changes, either in MDL-55171, where the full language of the proposals and the discussion so far has taken place, or here too.
Are there any things that we have not considered and should? Do you think that we should, or should not, switch to an LTS-linked deprecation policy?