Add page about upgrading

Fixes #3121

docs/en/index.rst

@@ -30,6 +30,7 @@ Contents:
    reference/portability
    reference/caching
    reference/known-vendor-issues
+   reference/upgrading
 
 Indices and tables
 ==================

docs/en/reference/upgrading.rst

@@ -0,0 +1,53 @@
+Upgrading
+=========
+
+New versions of Doctrine come with an upgrade guide named UPGRADE.md.
+This guide documents BC-breaks and deprecations.
+
+Deprecations
+------------
+
+Deprecations are signaled by emitting a silenced ``E_USER_DEPRECATED``
+error, like this:
+
+.. code-block:: php
+
+    <?php
+
+    @trigger_error(
+        'QuantumDefraculator::__invoke() is deprecated.',
+        E_USER_DEPRECATED
+    );
+
+Since this error is silenced, it will not produce any effect unless you
+opt-in by setting up an error handler designed to ignore the silence
+operator in that case. Such an error handler could look like this:
+
+.. code-block:: php
+
+    <?php
+    set_error_handler(function (
+        int $errno,
+        string $errstr,
+        string $errfile,
+        int $errline,
+        array $errcontext
+    ): void {
+        if (error_reporting() === 0) {
+            // "normal" error handlers would return in this case
+            if ($errno === E_USER_DEPRECATED) {
+                // but if this is a deprecation, let us do something:
+                echo "Hey there was a deprecation, here is what it says: $errstr";
+            }
+
+            return;
+        }
+
+        // normal error handling here
+    });
+
+This is of course overly simplified, and if you are looking for such an
+error handler, consider the ``symfony/debug``, error handler that will
+log deprecations. You may also be interested by the
+``symfony/phpunit-bridge`` error handler that will display deprecations
+after running your test suites.