Compatibility policy, guarantees and docs

[boenrobot]

As a continuation of the discussion in #360 ...

This project is very unique in what it's supposed to provide, and there are perhaps different equally valid views on how far it needs to go, especially in cases where full cross version compatibility may be impossible.

I'll start with my opinion on what I think the guarantees and policies should be. Further points and/or further nuance discussion is welcomed and is the whole reason for this issue.

1. It should be possible to write applications that work with both zf 1.12 and zf1-future on a given PHP version This PHP version should be the starting point of projects trying to move into later PHP versions while still keeping the majority of their zf1 code. The following points are just a consequence of this particular point.
2. PHP 7.1 should be the minimum supported version, always. Why? Because that is the last version that zf 1.12 supports without any errors, thus enabling point 1.
3. zf1-future should NOT cater to compatibility with PHP versions earlier from the latest PHP 7.1 (7.1.33, unless PHP decides to do some extraordinary "out of support cycle" release). This means that the migration path for applications is to first do whatever changes they need to do in the rest of the application to be PHP 7.1 compatible, and move to PHP 7.1 with zf 1.12 before even considering zf1-future. If compatibility with earlier PHP versions can be kept, great, but if a PR makes a change that works better in PHP 7.1+ (performance, security, etc.) at the cost of compatibility break with earlier PHP versions, that should be an acceptable break.
4. zf1-future should only break compatibility with zf 1.12 if there is an easy and sound way to have the affected code be changed in a way that works with both zf 1.12 and zf1-future without any sort of version checks. If such a case is encountered, it should be explicitly documented somewhere what the change is and how to make it work across zf 1.12 and zf1-future. This doc should be easy to discover (so either in README.md itself, or in a link in README.md). Ideally, it should be a change that applications are unlikely to be affected by in a typical application, though of course, what's "unlikely" and "typical" is subjective and to be determined on a case by case basis.
5. When using any code defined in zf1-future in any of the documented fashions, no notices, warnings or errors should be produced in any PHP version supported by zf1-future. Or at least that should always be the aim, and any PR that makes fixes towards that should be acceptable. Using zf1-future in a way that is not what's documented in zf 1.12 or zf1-future is fair game for compatibility breaks, even if a legacy application "relied" on a bug under the assumption that zf is frozen.
6. Some classes in the framework can be extended, and are in fact meant to be extended. Some of the more typical examples are Zend_Db_Table_Abstract, Zend_Db_Table_Row_Abstract, Zend_Controller_Action, Zend_Application_Bootstrap_Bootstrap. Different applications may also need to extend some of the classes that are not necessarily meant to be extended, but are extendable and often extended non the less (such as Zend_Form). With regards to these, zf1-future should find it acceptable to break compatibility of such user code, but only to the extent that one can possibly refactor the extending class to be compatible with both zf 1.12 and zf1-future on PHP 7.1 (sort of like already mentioned previously). Conversely, any change that makes it impossible to write such extended code should be rejected, even if it is required for compatibility with later PHP versions.
7. zf1-future should aim to support the highest PHP version it can, where none of the previous guarantees would be broken. If a PHP change makes it impossible to achieve such cross version compatibility, on a case by case basis, an option, a new method or a new class (that could otherwise be a drop-in replacement for the old) can be created, and the application can be encouraged to use that through the doc comments. Preferably without the need for a version check at the application level.
8. User code should have ways to opt into new PHP version specific behaviors, which may in turn have better performance, security, etc. but the default should be to have consistent behavior between supported PHP versions. A code that is zf 1.12 and zf1-future compatible on PHP 7.1 should be able to exhibit the same behavior on any supported PHP version without changes, or with changes, exhibit different behaviors based on the PHP version. This enables application authors to gradually migrate to those new behaviors as they upgrade their supported PHP versions.
   • This point is maybe a more controversial one, and likely to be applied inconsistently... There are often valid reasons to "simply" use whatever the most secure/efficient option based on the PHP version. IMO, this should be done only in cases where there is a way for the code to automatically fallback to the less secure/efficient approach without any code changes. f.e. adding more secure ciphers that are also preferred by default where there is cipher negotiation is fine. Switching out the default MySQL auth mechanism based on PHP version is not, because there is no negotiation for those.
9. Addition of new features should be minimal, and limited to enabling the continuing work of zf1 applications with the same 3rd party software that has previously been supported (ideally as drop in replacements).
   • ~For example, there is an SQLite driver that is using the sqlite extension... It may be reasonable to make a new driver that uses SQLite3, but is otherwise identical in behavior. On the other hand, MongoDB for example was not supported in zf1, and so a MongoDB driver should be out of scope for zf1-future.~ SQLite is perhaps a bad example, because the old SQLite has been dropped in PHP 5.4, so any application that first moves to PHP 7.1 will need to switch to something else even before it reaches zf1-future... Unless it jumps straight from "PHP 5.3 with zf 1.12" to "PHP 7.1 with zf1-future", skipping the "PHP 7.1 with zf 1.12" step, and the SQLite driver is changed to use SQLite3 instead of a new one being added, thus allowing this jump.
   • For example, adding ways to adjust the MySQL auth or encryption settings, while defaulting them to some cross version compatible ones is OK, as those new settings may be needed to enable work with newer versions of MySQL.

[develart-projects]

Let me comment on this one. I think we have mainly 3 approaches here:

1) just keep ZF1 running with as little changes as possible 2) 1+ let's do some minor enhancements to functionality, but maintaining backward compatibility and write down possible clashes 3) keep evolving towards strict type-ing, because new PHP enforcing that, while maintaining older v7 versions.

Imo 1+2 are for people like myself, running bunch of actively maintained ZF1 projects, expecting as little unnecessary work as possible.

3 is for people pushing towards Linting with all the types and stuff with no budget restriction on existing code rewrite/adjustments.

That's the summary of what I can see here.

Now, 1 and 3 are incompatible. So there isn't any real approach how to keep everybody happy. At least until we are supporting all 7 and 8 versions. On top of that, I think we are nearing inevitable clash with higher PHP8 versions. But that's another story.

Maybe we can give up keeping this as one project/repo/main version? And have 2 versions to keep happy everyone? Sure, this will add some manual work, like porting fixes and small enhancements, but can do the job.

I haven't any strong opinion on what is better, just like to find some conclusive answer.

[tsmgeek]

Nearly all apps that were written originally for 7.1 can without much work be updated to 7.4 and not much work after can get to 8 & 8.1

I think as this project moves forward it should look to deprecate the older PHP versions say 1-2y after the end of security patches, and that time window needs to also depend on blockers for newer PHP versions.

The main reasoning for me to keep ZF1 going imo is not itself to stay on very old PHP versions but to know that the framework is getting upgrades for supported PHP versions and it does not bring in sweeping changes that will require major rewrites to existing projects. Where its easy to support older versions then great do so, but if its blocking adding 8.3 support and all we need to do is raise minimum version to 7.4 then I say that is reasonable.

All my ZF apps are now on PHP 8.1 and starting to be tested on 8.2 shortly.

As for new features, I am not opposed to it, ie I contributed a Sendgrid SMTP library, may have not been the best idea to put it in as then it becomes responsibility for the project to maintain but at the same time say Captcha V2/3 may be a good idea as its a progression of the now broken version in the library.

A zf1-future-extras may be an idea for community supported plugins, but sometimes the plugins need to change core ZF functionality that is private/protected and it can be hard to implement a plugin without it being in the core due to limits on how extensible ZF1 is.

[WebTigers]

I'm going to have to hang on to 7.4 for now until some of these bugs for 8.1 get resolved. I will move on to 8.1+ as things move ahead. I can throw a little $$ at these issues to compensate for peoples' time if necessary, I don't mind doing that if it helps get things done more quickly, but I need stability before moving into 8.1 for a couple of my projects. Just opened a new bug regarding named parameters.