Deprecation policy

[oliverklee]

This is the general deprecation policy I'd like to suggest both for code removal and for renaming public things:

1. create the new method(s) (if there is a replacement) and redirect the old methods to the new ones
2. create a ticket in the next breaking milestone x.0.0 after the next release: "Drop it" which gets the ID yyy
3. add `@deprecated yyy will be removed in x.0.0" annotations to the old method(s)
4. once we're working on x.0.0, drop the old method(s)

This allows users of our package to keep using the old method(s) for some time and automatically scan their code for usages of the deprecated methods (using their IDE or a PHPStan ruleset).

Would this work for you, @sabberworm @JakeQZ?

And yes, I think having good, clear, easy-to-understand and hard-to-misunderstand names is immensely important and often makes this worth the hassle.

[JakeQZ]

Agree in general.

This should also apply to protected methods and properties that are renamed (since users might have extended the classes - though maybe you meant 'public' in this looser sense).

The magic __get and __set would need to be used for renamed properties during the transition (to chain property access akin to chaining method calls). I don't know if or how it's possible to mark a property as deprecated if it is removed but still accessible through these 'magic' methods.

I'd prefer to wait 3 years before removing the deprecated methods/properties, rather doing so immediately for the next major release. The rationale is that if you're maintaining a project that supports multiple PHP versions, and multiple versions of other components, it could lead to some very tight version constraints leading to difficulties supporting the latest PHP version. The reason for 3 years, is that that's how long before a new major PHP release becomes EOL.

We could also trigger an E_USER_DEPRECATED error when deprecated methods/properties are called/accessed (once only per method/property per process). Though some people might prefer not to have these clogging up their logfile, whilst also not wishing to disable all deprecation warnings (via error_reporting).

[oliverklee]

This should also apply to protected methods and properties that are renamed (since users might have extended the classes - though maybe you meant 'public' in this looser sense).

Yes, I fully agree. (That also means that we want to make as many methods and properties as possible private first to reduce the further hassle.)

I don't know if or how it's possible to mark a property as deprecated if it is removed but still accessible through these 'magic' methods.

No, it's not AFAIK.

TYPO3 uses a trait for making public properties as deprecated, which we could stealcopy: https://review.typo3.org/c/Packages/TYPO3.CMS/+/52928

We could also trigger an E_USER_DEPRECATED error when deprecated methods/properties are called/accessed

Yes, sounds like a good plan.

I'd prefer to wait 3 years before removing the deprecated methods/properties, rather doing so immediately for the next major release. The rationale is that if you're maintaining a project that supports multiple PHP versions, and multiple versions of other components, it could lead to some very tight version constraints leading to difficulties supporting the latest PHP version. The reason for 3 years, is that that's how long before a new major PHP release becomes EOL.

I'd prefer to be able to remove deprecated things sooner. Maybe we can have maintenance branches of released major versions where we only fix problems with higher PHP versions - similar to the "life support" approach from PHPUnit: https://phpunit.de/supported-versions.html

What do you think?

[JakeQZ]

That also means that we want to make as many methods and properties as possible private first to reduce the further hassle.

To make them private we'd also need to first deprecate them as public/protected, and wait for the next major release before changing them to private. Not sure how that could be achieved in DocBlock or technically re emitting a deprectation warning, if they are not also being renamed.

Maybe we can have maintenance branches of released major versions where we only fix problems with higher PHP versions

That would work.

[JakeQZ]

Maybe we can have maintenance branches of released major versions where we only fix problems with higher PHP versions

That would work.

Though it would also be good to include other bug fixes (as both PHP and WordPress do).

[oliverklee]

Not sure how that could be achieved in DocBlock or technically re emitting a deprectation warning, if they are not also being renamed.

We probably can also use the trait from TYPO3 for that.

[oliverklee]

Though it would also be good to include other bug fixes (as both PHP and WordPress do).

Fine with me (for the cases where it’s not too much of a hassle for us).

[oliverklee]

I have created an 8.x branch and backported some changes that hopefully will make working on the branch and backporting things to it easier.