PHPLIB-601: Document upcoming typing changes

[alcaeus]

PHPLIB-601

I've added an UPGRADE-1.14 document to inform users of changes they should be aware of when upgrading. Once changes for 2.0 become clearer (including a list of methods that will change their return types), we should add an UPGRADE-2.0 document to inform users of those.

@jmikola I've renamed the previous upgrade guide in the docs to "Legacy driver upgrade guide", in case we want to add a more visible documentation of method signature changes once we add BC breaks in 2.0. I've skipped a list of changes for this PR, but can list method signature changes in the upgrade document as well. An example of this is the upgrade document for doctrine/collections where interfaces were changed to add types.

We'll want to consider where to document upcoming return type changes for ext-mongodb. While users on PHP 8.1 and newer will be informed of tentative return types, users on previous version will not be aware of those changes. At the same time, as most users will consume the extension through this library (but may interact with extension classes directly), I'm not sure what the best place to document those changes are.

For now, I believe this document is sufficient to inform users of changes we've already made, as well as upcoming changes to internal classes.

[jmikola]

That's quite the old typo correction!

[jmikola]

I've skipped a list of changes for this PR, but can list method signature changes in the upgrade document as well. An example of this is the upgrade document for doctrine/collections where interfaces were changed to add types.

That format looks good to me.

We'll want to consider where to document upcoming return type changes for ext-mongodb. While users on PHP 8.1 and newer will be informed of tentative return types, users on previous version will not be aware of those changes.

Two thoughts here. Does it make sense to document all signature changes in the PHPC method changelogs? That seems like the expected place for it and would certainly be more accessible than a separate page in the PHP.net docs that might be easily overlooked.

I also wouldn't object to including PHPC API changes in this document, since those are going to arrive in the corresponding PHPC release (1.15 for PHPLIB 1.14).

[alcaeus]

Does it make sense to document all signature changes in the PHPC method changelogs?

Yes. I've already added a note about tentative return types (see php/doc-en@734bafe), but calling out other changes (such as widening parameter types, etc.) should also be called out. I'll go through the changes and make sure that those are updated.

There aren't any other significant API changes for users, as we've only changed final classes in PHPC. However, it will become relevant for 2.0, at which point I'd definitely point out PHPC API changes in this upgrade document as well where it affects users.

[jmikola]

Just a few suggestions you can apply and merge as you wish.

Take another look at the rendered Markdown file before merging, as that's how I caught some of the formatting mistakes.

[jmikola]

Good catch!