Deprecated the usage of the Version class

[morozov]

Q	A
Type	deprecation
BC Break	no

[greg0ire]

I think this will result in a deprecation for users of https://github.com/symfony/error-handler/blob/master/DebugClassLoader.php . Wouldn't marking it as @internal be enough to warn users against using it, and maybe more semantically correct?

[SenseException]

It is removed in master. AFAIK master is going to be 4.0, so the deprecation message should contain the information when this class will be removed.

[morozov]

I think this will result in a deprecation for users of https://github.com/symfony/error-handler/blob/master/DebugClassLoader.php.

The problem is not the deprecation but how it's being handled. In our case, we're just adding an annotation purely for documentation purposes. If a 3rd party component turns this annotation into an undesired runtime side effect, the problem is in the component. Do users use it in production? The "debug" name suggests they shouldn’t.

Wouldn't marking it as @internal be enough to warn users against using it, and maybe more semantically correct?

I don't know. Both annotations are standard and correspond to the messages I want to communicate:

1. @intermal — the class is an implementation detail and shouldn’t be relied upon outside of the package. It should have been marked like this since the introduction.
2. @deprecated — the class is going to be removed in a following major release.

It is removed in master. AFAIK master is going to be 4.0, so the deprecation message should contain the information when this class will be removed.

We don't usually do that.

[greg0ire]

If it's removed on master, then @deprecated should stay 👍

[greg0ire]

Do users use it in production? The "debug" name suggests they shouldn’t.

You're right, that probably makes this quite ok.

[alcaeus]

I have no problem with both @internal and @deprecated, since they are different. The explanation @morozov gave above is perfectly correct.

As for the version, these are my thoughts:

• If we deprecate something and don't know when it will be released, we should say "in a future major release" as that's what will happen
• Once we know what release removes the member, we should update the deprecation message to state the version that removes it. Even if we deprecate in 2.x for removal in 4.0, we should mention that the class will be removed in 4.0. Users that are interested in the deprecations will appreciate the information as it lets them decide when to take care of the deprecation.

[morozov]

If we deprecate something and don't know when it will be released, we should say "in a future major release" as that's what will happen

I'm fine with this definition of “when” — “in a future major release”, however, isn’t implied by semver? It definitely cannot happen earlier.

Once we know what release removes the member, we should update the deprecation message to state the version that removes it.

This is why I don't want to specify any exact versions. Specifically in DBAL, we don’t know that upfront and I don’t want to introduce additional work on updating deprecation comments.

Users that are interested in the deprecations will appreciate the information as it lets them decide when to take care of the deprecation.

I didn’t think people may be really interested in the exact version. What is the practical reason for interest in a specific removal version? In our case, even if we mention a specific version, we don’t have any release dates for those versions.