how do I make sure that the config setting is used only for ORM versions that already support it?

You may use feature detection with trait_exists(ReflectionBasedDriver::class)

And once we're at Doctrine 3.0, how to notify users that the setting is a no-op and should be removed?

Likewise, use feature detection based on something hopefully related to this feature.

@ostrolucky Do I need the UPGRADE entry when there is nothing users have to do during the upgrade? They can opt in at any time as long as ORM ^2.16 is available.

Don't get me wrong, I'll update configuration.rst for sure.

how do I make sure that the config setting is used only for ORM versions that already support it?

You may use feature detection with trait_exists(ReflectionBasedDriver::class)

And once we're at Doctrine 3.0, how to notify users that the setting is a no-op and should be removed?

Likewise, use feature detection based on something hopefully related to this feature.

Not sure this is going to work, since I cannot tell whether I am before ORM 2.16 (config setting makes no sense, need not be available) or at ORM 3.0 (config setting should be removed).

Can I use https://getcomposer.org/doc/07-runtime.md#knowing-whether-package-x-is-installed-in-version-y – that requires Composer 2.x?

I cannot tell whether I am before ORM 2.16 (config setting makes no sense, need not be available) or at ORM 3.0 (config setting should be removed).

Well you could check if ClassMetadataInfo exists, for instance.

Can I use https://getcomposer.org/doc/07-runtime.md#knowing-whether-package-x-is-installed-in-version-y – that requires Composer 2.x?

Might be fine as well.

@ostrolucky Do I need the UPGRADE entry when there is nothing users have to do during the upgrade?

I'm basing this on what we have in UPGRADE-2.9.md but IIRC we don't document things that users have to change only, but also things that should be changed. Especially things that help them avoid deprecations. I mean, let's say ORM 3.x or 4.x decides to throw exception if you don't set the value to true. In which UPGRADE-* file would you suggest then to do add this docs once such ORM is released and all users code starts breaking because they didn't change that config?

The thing is that users should set the config option once they upgrade doctrine/orm to >= 2.16, and remove it when they upgrade doctrine/orm to >= 3.0. Both times, they probably don't look at DoctrineBundle upgrade notes, but rather at the doctrine/orm ones.

It may happen that when making the DoctrineBundle 2.10 upgrade, ORM 2.16 will not even be released in the first place.

Again, check how UPGRADE-2.9.md is written. It explains everything, similar like you explained in your last comment, that's how it should be. We are not just going to tell user to set it, but to set it if they use ORM 2.16 and to do it if they want to solve deprecation and prepare for ORM 3.

they probably don't look at DoctrineBundle upgrade notes, but rather at the doctrine/orm ones.

Opposite for me. I don't look at orm notes because they are often meaningless in symfony context. For example orm notes will tell you to set some argument of some class/function, that's meaningless in context of symfony user. Symfony user needs to know which config value they need to flip in doctrine.yaml, since bundle is doing the passing of the argument and not the user.

Maybe we can just bump the conflict to <2.16 for the ORM (once released?) to address the challenge you mentioned in the PR description?

I have added an explanatory text in a new UPGRADE-2.10.md file, explaining the changes and possible impact.

Regarding feature detection, what if we simply go without it?

Turning the new flag on for pre-ORM 2.16 does no harm: It adds a new constructor parameter to mapping drivers that will simply be ignored.

For ORM ^2.16, the ORM will trigger a deprecation notice unless the flag is turned on.

In ORM ^3.1, a deprecation notice will be triggered stating that the flag is a no-op and the configuration should be removed.

... so maybe nothing we need to take care of here at all?

Yeah I think it's good enough like this. Can you rebase? Then we can merge.

@ostrolucky Rebased, thank you

This misses the update of the XSD file (so the documented configuration for the XML format will break)