From 633fa7b2e851a6aaa0d86c89cd3225a03ae7365d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Gr=C3=A9goire=20Paris?= <postmaster@greg0ire.fr>
Date: Tue, 1 May 2018 12:55:56 +0200
Subject: [PATCH 1/2] Make executables executable

---
 docs/bin/generate-docs.sh        | 0
 docs/bin/install-dependencies.sh | 0
 2 files changed, 0 insertions(+), 0 deletions(-)
 mode change 100644 => 100755 docs/bin/generate-docs.sh
 mode change 100644 => 100755 docs/bin/install-dependencies.sh

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

From 041a7697bf7777184bff97728bf2130f0f381be7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Gr=C3=A9goire=20Paris?= <postmaster@greg0ire.fr>
Date: Tue, 1 May 2018 12:56:16 +0200
Subject: [PATCH 2/2] Add page about upgrading

Fixes #3121
---
 docs/en/index.rst               |  1 +
 docs/en/reference/upgrading.rst | 51 +++++++++++++++++++++++++++++++++
 2 files changed, 52 insertions(+)
 create mode 100644 docs/en/reference/upgrading.rst

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.