Now that we have regular LTS releases, I would like to propose that we update our deprecation policy.

Below are two proposals. Proposal A was the original proposal. Proposal B is the newer (preferred by me) proposal.

Proposal B

I've been giving this some more thought and feel that we should be stricter still than proposal A.
Our current process is to deprecate code but attempt to keep it working, and then later to convert that working code to an exception.

I'd like to propose that we:
a) keep the initial proposal as-is (keep working where possible or throw exception if not);
b) update the current exception throwing part of the policy to just outright remove code; and
c) tie the removal to the LTS releases.

Note: Where we have an initial deprecation where we cannot call the new API we should still use the exception process that we currently use.

I would suggest that we perform the removal in the Moodle release immediately after the next LTS release.
If a deprecation happens in an LTS release, then the 'next' LTS release is the release after that version.

Removal of deprecated code MUST happen in the release immediately after the next LTS release.
Deprecations which take place in an LTS release WILL NOT be considered for removal until the following LTS release.
A minimum of two releases MUST occur between initial deprecation and removal of code.

Examples

Example 1

I deprecate a function in mod/forum/lib.php in master to be included in the Moodle 3.8 release.

Moodle 3.8 is a regular release.
The LTS release following the 3.8 release is 3.9.
Therefore removal of the code will occur in the Moodle 4.0 release, as that is the release after the 3.9 LTS release following the 3.8 release that the initial deprecation occurred in.

Example 2

I deprecate a function in mod/forum/lib.php in master to be included in the Moodle 3.9 release.

Moodle 3.9 is an LTS release.
The LTS release following the 3.9 release is 4.3.
Therefore removal of the code will occur in the Moodle 4.4 release, as that is the release after the 4.3 LTS release following the 3.9 release that the initial deprecation occurred in.

Andrew's thoughts on this proposal

1. It's a much more stringent timeline
2. Some people running the Moodle version before an LTS release will only have 12 months to update their code.
3. Anyone running releases which are between LTSs is likely to be updating regularly anyway, so are less likely to be affected by the removal cadence anyway
4. Fit much better with PHP support cadences

Proposal C

This is almost identical to Proposal B, but with removal happening in the release immediately prior to an LTS release.

Removal of deprecated code MUST happen in the release immediately before the LTS release after the next LTS release.
Deprecations which take place in an LTS release WILL NOT be considered for removal until after the following LTS release.
A minimum of one LTS release must occur.

Examples

Example 1

I deprecate a function in mod/forum/lib.php in master to be included in the Moodle 3.8 release.

Moodle 3.8 is a regular release.
The LTS release following the 3.8 release is 3.9.
The LTS release after that is 4.3
Therefore removal of the code will occur in the Moodle 4.2 release, as that is the release immediately before the 4.3 LTS release.

Example 2

I deprecate a function in mod/forum/lib.php in master to be included in the Moodle 3.9 release.

Moodle 3.9 is an LTS release.
The LTS release following the 3.9 release is 4.3.
The LTS release after that is 4.7
Therefore removal of the code will occur in the Moodle 4.6 release, as that is the release after the 4.3 LTS release following the 3.9 release that the initial deprecation occurred in.

Andrew's thoughts on this proposal

1. It's a reasonable middle-ground between the current situation, and proposal B, but it does lead to extremely long LTS processes
2. The concern with a 3.5 year process is that with the PHP cadence, we may have code which is deprecated and not yet removed and incompatible with a PHP release
3. Does this actually service anyone?

Proposal A

1) Initial deprecation (as current process)
2) Intermediate deprecation
3) Final deprecation

Initial deprecation

1. Affects public master APIs
2. At any time on master only
3. Existing functionality is maintained with a debugging message unless this is not possible.

Intermediate deprecation

1. Happens at LTS + 1 for anything deprecated at LTS - 1
2. Anything deprecated prior to the release of an LTS is eligible for code removal and can be replaced by an exception.

Final deprecation

1. Functions are eligible for removal on LTS + 1 of the next LTS
2. No requirement to note in upgrade.txt

Examples

LTS releases: 2.7, 3.1, 3.5, 3.9

Rationale and explanation

This is a big change in that we are now deprecating things in the NEXT LTS. So if we deprecated something in 3.4, we will break it in 3.5 (LTS) rather than the current 3.8. This means that we only process deprecations in LTS + 1.

There are many examples of code in Moodle which have been deprecated since the very early days. In the forum, for example, we have code which has been deprecated since Moodle 1.1. There must be a time where it becomes safe to remove entirely.

This is especially true when the deprecated functionality was not replaced. In this case, the exception thrown will just say that the function cannot be used any more. There is no replacement. There's very little benefit to even having the exception over removing the function entirely - about the only thing which springs to mind is that the function will continue to exist and therefore a similarly named one cannot be created.