diff --git a/docs/bin/generate-docs.sh b/docs/bin/generate-docs.sh
old mode 100644
new mode 100755
diff --git a/docs/bin/install-dependencies.sh b/docs/bin/install-dependencies.sh
old mode 100644
new mode 100755
diff --git a/docs/en/index.rst b/docs/en/index.rst
index 5f9c64d9a51..90d0f8159d2 100644
--- a/docs/en/index.rst
+++ b/docs/en/index.rst
@@ -30,6 +30,7 @@ Contents:
    reference/portability
    reference/caching
    reference/known-vendor-issues
+   reference/upgrading
 
 Indices and tables
 ==================
diff --git a/docs/en/reference/upgrading.rst b/docs/en/reference/upgrading.rst
new file mode 100644
index 00000000000..1fff13472e0
--- /dev/null
+++ b/docs/en/reference/upgrading.rst
@@ -0,0 +1,51 @@
+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, but
+               this one will not */
+        }
+
+        echo "Hey there was a deprecation, here is what it says: $errstr";
+
+    }, E_USER_DEPRECATED);
+
+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 catch deprecations
+and nicely display them after running your test suites, and can even
+make your build fail in that kind of case if you want to be strict about
+that.