Deprecate the Synchronizer package

[morozov]

Q	A
Type	deprecation
BC Break	no

Summary

The SchemaSynchronizer API was introduced as part of the support for sharding (#162) which is now deprecated (#3905). This code hasn't received any functional changes in the last 8 years (12f381f) and doesn't seem to be used by any open source projects.

According to the tests and the implementation, SingleDatabaseSynchronizer is just a wrapper over other schema-related APIs and doesn't provide any additional functionality.

[morozov]

From #162:

It is self-contained and does not affect the normal DBAL code.

It's a perfect example of why “let's add this code to the library because another project may need to use it” is a bad idea.

[greg0ire]

There still seems to be references to this in docs: https://github.com/doctrine/dbal/blob/2.11.x/docs/en/reference/sharding.rst#schema-operations-schemasynchronizer-interface Should these docs have been removed, or maybe marked as deprecated in #3905 ? IMO we should not advertise deprecated features.

[morozov]

IMO we should not advertise deprecated features.

Well, we're not necessarily advertising them, it's just documentation. I'll make sure it's removed during the up-merge. In any event, the whole "Sharding" section will be removed from the documentation, not only this specific API.

[greg0ire]

I mean that we should maybe remove it from 2.11.x too, or at least make it clear that sharding is deprecated in the docs

[morozov]

I mean that we should maybe remove it from 2.11.x too […]

Removing documentation for the existing code looks odd to me.

[…] or at least make it clear that sharding is deprecated in the docs

We haven't been doing this for any other deprecations, so we're at least consistent here. Otherwise, there's a lot more to update than just this.

UPD: in fact, what the right approach is depends on what type of documentation that is. It would indeed make sense to remove it from a How-To or a Tutorial but kept in Explanation or Reference. Ours is all-in-once, so there's no right or wrong answer.

[greg0ire]

Nice resource, thanks for sharing it!
After a quick look, I'd say that https://github.com/doctrine/dbal/blob/2.10.x/docs/en/reference/sharding.rst is more of a How-to guide, while
https://github.com/doctrine/dbal/blob/2.10.x/docs/design/SHARDING.md looks like an explanation, but there might be other types leaking in both documents. What would you say the right approach is for each type?

[morozov]

What would you say the right approach is for each type?

I suggest we take the same approach as for sharding: don't make any documentation changes during the deprecation (#3905) and removed the documentation during the code removal (#3906).

If we want to change this process, it's out of the scope of this issue and should be done separately.

[morozov]

On the other hand, we do have some APIs (e.g. platforms) marked as deprecated in the documentation. But it's more of an exception than a rule:

$ git grep -i deprecated lib/ 2.11.x | wc -l
354

$ git grep -i deprecated docs/ 2.11.x | wc -l
15

I went ahead and updated the documentation on SchemaSynchronizer.