Merge pull request #5117 from radarhere/versioning

Added versioning documentation

RELEASING.md

@@ -1,5 +1,8 @@
 # Release Checklist
 
+See https://pillow.readthedocs.io/en/stable/releasenotes/versioning.html for
+information about how the version numbers line up with releases.
+
 ## Main Release
 
 Released quarterly on January 2nd, April 1st, July 1st and October 15th.

docs/releasenotes/index.rst

@@ -3,7 +3,8 @@ Release Notes
 
 Pillow is released quarterly on January 2nd, April 1st, July 1st and October 15th.
 Patch releases are created if the latest release contains severe bugs, or if security
-fixes are put together before a scheduled release.
+fixes are put together before a scheduled release. See :ref:`versioning` for more
+information.
 
 Please use the latest version of Pillow. Functionality and security fixes should not be
 expected to be backported to earlier versions.
@@ -48,3 +49,4 @@ expected to be backported to earlier versions.
   3.0.0
   2.8.0
   2.7.0
+  versioning

docs/releasenotes/versioning.rst

@@ -0,0 +1,30 @@
+.. _versioning:
+
+Versioning
+==========
+
+Pillow follows [Semantic Versioning](https://semver.org/):
+
+    Given a version number MAJOR.MINOR.PATCH, increment the:
+
+    1. MAJOR version when you make incompatible API changes,
+    2. MINOR version when you add functionality in a backwards compatible manner, and
+    3. PATCH version when you make backwards compatible bug fixes.
+
+Quarterly releases ("`Main Release <https://github.com/python-pillow/Pillow/blob/master/RELEASING.md#main-release>`_")
+bump at least the MINOR version, as new functionality has likely been added in the
+prior three months.
+
+A quarterly release bumps the MAJOR version when incompatible API changes are
+made, such as removing deprecated APIs or dropping an EOL Python version. In practice,
+these occur every 12-18 months, guided by
+`Python's EOL schedule <https://devguide.python.org/#status-of-python-branches>`_, and
+any APIs that have been deprecated for at least a year are removed at the same time.
+
+PATCH versions ("`Point Release <https://github.com/python-pillow/Pillow/blob/master/RELEASING.md#point-release>`_"
+or "`Embargoed Release <https://github.com/python-pillow/Pillow/blob/master/RELEASING.md#embargoed-release>`_")
+are for security, installation or critical bug fixes. These are less common as it is
+preferred to stick to quarterly releases.
+
+Between quarterly releases, ".dev0" is appended to the "master" branch, indicating that
+this is not a formally released copy.