Add deprecations and removals page to docs

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``).

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
 ==================