From b432f838f1d67fc280a6e33fe8d81cd328b06994 Mon Sep 17 00:00:00 2001
From: Andrew Murray <radarhere@users.noreply.github.com>
Date: Sat, 1 May 2021 22:53:46 +1000
Subject: [PATCH] Documented ImageOps contain method

---
 docs/reference/ImageOps.rst |  1 +
 docs/releasenotes/8.3.0.rst | 49 +++++++++++++++++++++++++++++++++++++
 2 files changed, 50 insertions(+)
 create mode 100644 docs/releasenotes/8.3.0.rst

diff --git a/docs/reference/ImageOps.rst b/docs/reference/ImageOps.rst
index 9a16d6625..d1c43cf60 100644
--- a/docs/reference/ImageOps.rst
+++ b/docs/reference/ImageOps.rst
@@ -12,6 +12,7 @@ only work on L and RGB images.
 
 .. autofunction:: autocontrast
 .. autofunction:: colorize
+.. autofunction:: contain
 .. autofunction:: pad
 .. autofunction:: crop
 .. autofunction:: scale
diff --git a/docs/releasenotes/8.3.0.rst b/docs/releasenotes/8.3.0.rst
new file mode 100644
index 000000000..4459083ea
--- /dev/null
+++ b/docs/releasenotes/8.3.0.rst
@@ -0,0 +1,49 @@
+8.3.0
+-----
+
+Deprecations
+============
+
+TODO
+^^^^
+
+TODO
+
+API Changes
+===========
+
+TODO
+^^^^
+
+TODO
+
+API Additions
+=============
+
+ImageOps.contain
+^^^^^^^^^^^^^^^^
+
+Returns a resized version of the image, set to the maximum width and height within
+``size``, while maintaining the original aspect ratio.
+
+To compare it to other ImageOps methods:
+- :py:meth:`~PIL.ImageOps.fit` expands an image until is fills ``size``, cropping the
+parts of the image that do not fit.
+- :py:meth:`~PIL.ImageOps.pad` expands an image to fill ``size``, without cropping, but
+instead filling the extra space with ``color``.
+- :py:meth:`~PIL.ImageOps.contain` is similar to :py:meth:`~PIL.ImageOps.pad`, but
+it does not fill the extra space. Instead, the original aspect ratio is maintained. So
+unlike the other two methods, it is not guaranteed to return an image of ``size``.
+
+Security
+========
+
+TODO
+
+Other Changes
+=============
+
+TODO
+^^^^
+
+TODO