From b4e485ca538d0981c42e7c75a49e1c3546af4f24 Mon Sep 17 00:00:00 2001
From: Hugo <hugovk@users.noreply.github.com>
Date: Thu, 6 Dec 2018 10:56:07 +0200
Subject: [PATCH 1/2] Add deprecations and removals page to docs

---
 docs/deprecations.rst | 78 +++++++++++++++++++++++++++++++++++++++++++
 docs/index.rst        |  1 +
 2 files changed, 79 insertions(+)
 create mode 100644 docs/deprecations.rst

diff --git a/docs/deprecations.rst b/docs/deprecations.rst
new file mode 100644
index 000000000..412bcb591
--- /dev/null
+++ b/docs/deprecations.rst
@@ -0,0 +1,78 @@
+.. _deprecations:
+
+Deprecations and removals
+=========================
+
+This page lists Pillow features that are deprecated, or have been removed in
+past major releases, and gives the alternatives to use instead.
+
+Deprecated features
+-------------------
+
+Below are features which are considered deprecated. Where appropriate,
+a ``DeprecationWarning`` is issued.
+
+Setting the size of TIFF images
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. deprecated:: 5.3.0
+
+Setting the image size of a TIFF image (eg. ``im.size = (256, 256)``) issues
+a ``DeprecationWarning``::
+
+    Setting the size of a TIFF image directly is deprecated, and will
+    be removed in a future version. Use the resize method instead.
+
+PILLOW_VERSION and VERSION constants
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. deprecated:: 5.2.0
+
+Two version constants – ``VERSION`` (the old PIL version, always 1.1.7) and
+``PILLOW_VERSION`` – have been deprecated and will be removed in the next
+major release. Use ``__version__`` instead.
+
+Undocumented ImageOps functions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. deprecated:: 4.3.0
+
+Several undocumented functions in ``ImageOps`` have been deprecated. They issue
+a ``DeprecationWarning`` informing which equivalent to use from ``ImageFilter``
+instead:
+
+==========================  ============================
+Deprecated                  Use instead
+==========================  ============================
+``ImageOps.box_blur``       ``ImageFilter.BoxBlur``
+``ImageOps.gaussian_blur``  ``ImageFilter.GaussianBlur``
+``ImageOps.gblur``          ``ImageFilter.GaussianBlur``
+``ImageOps.usm``            ``ImageFilter.UnsharpMask``
+``ImageOps.unsharp_mask``   ``ImageFilter.UnsharpMask``
+==========================  ============================
+
+PIL.OleFileIO
+~~~~~~~~~~~~~
+
+.. deprecated:: 4.0.0
+
+The vendored version of olefile has been removed. Attempting to import
+``PIL.OleFileIO`` issues a ``DeprecationWarning`` (from 4.0.0) or raises
+``ImportError`` (from 5.0.0)::
+
+    PIL.OleFileIO is deprecated. Use the olefile Python package
+    instead. This module will be removed in a future version.
+
+Removed features
+----------------
+
+Deprecated features are only removed in major releases after an appropriate
+period of deprecation has passed.
+
+Vendored olefile
+~~~~~~~~~~~~~~~~
+
+*Removed in version 4.0.0.*
+
+The vendored version of the olefile Python package was removed in favour of the
+upstream package. Install if needed (eg. ``pip install olefile``).
diff --git a/docs/index.rst b/docs/index.rst
index 112798c94..7a32bf486 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -43,6 +43,7 @@ Pillow is the friendly PIL fork by `Alex Clark and Contributors <https://github.
    porting.rst
    about.rst
    releasenotes/index.rst
+   deprecations.rst
 
 Indices and tables
 ==================

From 5eb7fa1a7816c719e516a24fdec212289854e9c2 Mon Sep 17 00:00:00 2001
From: Andrew Murray <radarhere@users.noreply.github.com>
Date: Sat, 8 Dec 2018 06:28:46 +1100
Subject: [PATCH 2/2] Stopped code highlighting

---
 docs/deprecations.rst | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/docs/deprecations.rst b/docs/deprecations.rst
index 412bcb591..8d0ccbf37 100644
--- a/docs/deprecations.rst
+++ b/docs/deprecations.rst
@@ -18,7 +18,9 @@ Setting the size of TIFF images
 .. deprecated:: 5.3.0
 
 Setting the image size of a TIFF image (eg. ``im.size = (256, 256)``) issues
-a ``DeprecationWarning``::
+a ``DeprecationWarning``:
+
+.. code-block:: none
 
     Setting the size of a TIFF image directly is deprecated, and will
     be removed in a future version. Use the resize method instead.
@@ -58,7 +60,9 @@ PIL.OleFileIO
 
 The vendored version of olefile has been removed. Attempting to import
 ``PIL.OleFileIO`` issues a ``DeprecationWarning`` (from 4.0.0) or raises
-``ImportError`` (from 5.0.0)::
+``ImportError`` (from 5.0.0):
+
+.. code-block:: none
 
     PIL.OleFileIO is deprecated. Use the olefile Python package
     instead. This module will be removed in a future version.