Introduce Doctrine\DBAL\Migrations\AbstractMigration deprecation.

[jwage]

Q	A
Type	improvement
BC Break	no
Fixed issues	Fixes #642

Summary

Prepare for the 2.0 release and deprecate things in 1.8

• Introduce forward compatibility layer for Doctrine\Migrations\AbstractMigration
• Deprecate Doctrine\DBAL\Migrations\AbstractMigration
• Update migration generation to use Doctrine\Migrations\AbstractMigration

[stof]

Do we have any place typehinting AbstractMigration or having it as a return type in a public API ? If yes, the current migration path (making the old class extend the new one) is a BC break.

[jwage]

I don't think we do, but why would it be a BC break? The type hint would still work.

[jwage]

@stof I understand what you mean now. I reversed the inheritance, but with this approach, the deprecation warning will never go away after they start using the new class. I am not sure the effort here of releasing 1.8 with this deprecation the forward compatibility is worth it. People can just change to use Doctrine\Migrations\AbstractMigration when they upgrade to 2.0

[jwage]

I had an idea to move the deprecation warning to the constructor and override the constructor in the new class but this has other implications. Let me know your thoughts.

[stof]

@jwage what you could do is trigger the deprecation in the constructor, but wrapped in a if (!$this instanceof NewClass) check. This way, no need to override the constructor (and so no need to make everything protected).

[mlocati]

This trigger_error broke our sites when upgrading from 1.7 to 1.8.
I wouldn't expect that a dot release breaks stuff...

[alcaeus]

This trigger_error broke our sites when upgrading from 1.7 to 1.8.
I wouldn't expect that a dot release breaks stuff...

This release didn't break anything. As required by Semantic versioning, the deprecation was introduced in a minor. release, with removal occurring in a future major release (in this case, 2.0). The deprecation causing an error is probably because of an error handler promoting deprecation warnings to outright errors, which shouldn't happen.

FWIW, the usage of such deprecation notices is very widespread in the Symfony ecosystem, especially for deprecations which can't easily be deprecated using the @deprecated annotation (think deprecating a specific code path). If something like this breaks your application, that's on you, not on us.

[mlocati]

Yes, we are rather strict about warnings.

What's the goal of this trigger_error? Let's assume we are locked to version 1.x because of dependencies: what should we do to remove this warning? Use the new Doctrine\Migrations\AbstractMigration class introduced in version 1.8.1? And what would happen if some other installation installs version 1.7?

IMHO people should take care of dependencies only when upgrading to a major release (eg 1.x -> 2.x). Triggering errors in dot releases should occur only in exceptional cases

[alcaeus]

IMHO people should take care of dependencies only when upgrading to a major release (eg 1.x -> 2.x). Triggering errors in dot releases should occur only in exceptional cases

Again, we are not triggering an error, we are triggering a deprecation notice. If you take those and convert them into errors (e.g. by throwing an exception that isn't handled), it is you triggering the error, not us.

You don't have to take care of this dependency until you upgrade to the new major version. However, if you want to, you can fix this issue once upgrading to 1.8 so you're prepared for 2.0 and don't have to take care of it then.

Let's assume we are locked to version 1.x because of dependencies: what should we do to remove this warning? Use the new Doctrine\Migrations\AbstractMigration class introduced in version 1.8.1?

That is correct. Once you upgrade to 1.8, you should use the new class (which removed the DBAL part in the namespace as migrations is no longer part of the DBAL package). You can also ignore the deprecation and make the change when upgrading to 2.0 - until then your code will work as expected (as everything else would be a BC break).

And what would happen if some other installation installs version 1.7?

If you have a class that extends the abstract migration class, you should own that version constraint. If you require a class that was only introduced in 1.8, your version constraint for doctrine/migrations in composer.json needs to be adjusted accordingly. I would suggest looking into a tool like composer-require-checker to help you with this.

I hope this information helps you deal with such deprecations better, but as a general rule you should not treat these as errors but rather informational messages. These messages are designed to be consumed using the Symfony PHPUnit Bridge, which logs all deprecation messages encountered during a phpunit run and displays them so you can start fixing them.

[mlocati]

You don't have to take care of this dependency until you upgrade to the new major version.

So, what's the purpose of this deprecation warning? If I use 1.x it's useless, and if I use 2.x we don't have the deprecated class.

That is correct. Once you upgrade to 1.8, you should use the new class

Well, since 1.8.1 doesn't changes anything vs 1.7.2 (except this deprecation warning), why should I even upgrade to 1.8.1? It would make sense if it was always possible to update dependencies, but many of them are out of our control, since they are dependencies of dependencies.
Sadly, dependencies in PHP are more strict than, for example, NodeJS dependencies (where we can have multiple versions of the same package).

I hope this information helps you deal with such deprecations better, but as a general rule you should not treat these as errors but rather informational messages.

We have a rather complex system, and any triggered error/warning rings the bells. That makes sense when we can actually do something to fix the problem, but in this particular case the only solution we have is to lock Doctrine Migrations to 1.7, which doesn't make sense to me.

[alcaeus]

So, what's the purpose of this deprecation warning? If I use 1.x it's useless, and if I use 2.x we don't have the deprecated class.

The purpose is that you know that you'll have to start using the new class in 2.0. You can do so already (since the class is there) and get rid of the deprecation notice (and not have to change it when upgrading to 2.0), or you can ignore the notice and fix this when upgrading.

Well, since 1.8.1 doesn't changes anything vs 1.7.2 (except this deprecation warning), why should I even upgrade to 1.8.1? It would make sense if it was always possible to update dependencies, but many of them are out of our control, since they are dependencies of dependencies.

If these are dependencies of dependencies and you don't use the class directly, file an issue in the library that you are using. In that case you should definitely not care about the deprecation notice (let alone convert it to an error). If you have an extends AbstractMigration in your code, it is no longer a dependency of a dependency and should appear in your composer.json.

We have a rather complex system, and any triggered error/warning rings the bells. That makes sense when we can actually do something to fix the problem, but in this particular case the only solution we have is to lock Doctrine Migrations to 1.7, which doesn't make sense to me.

The solution is to not convert deprecations to errors or handle them appropriately after converting them.

[mlocati]

The purpose is that you know that you'll have to start using the new class in 2.0.

Upgrading to major versions is a manual process: you have to read the changelogs to see what changed. Adding this logic to the code doesn't make much sense to me.

[alcaeus]

With these notices, your test suite can inform you where you're using deprecated functionality, instead of you having to manually find it. Either way, if you don't want to use them, ignore them: failing hard on an E_USER_DEPRECATED is your choice (and it's wrong IMO), but we're not going to stop adding these deprecation notices just because you're reducing different log severities to a fatal error.

[jwage]

It is also worth mentioning that this deprecation strategy is a very well established and documented standard in the php oss community. See https://symfony.com/doc/current/contributing/code/conventions.html and https://www.doctrine-project.org/policies/deprecation.html