python/README: Add deprecation notice / schedule

This describes the proposal outlined in #8520, with a few
additions/modifications:

* Describes the handling of the Python 2 interpreter

* Allows for normal updates of Python 2 libraries that share the same
  Makefile as their Python 3 version

* Mass removal event has a name

Supersedes #8788.

Signed-off-by: Jeffery To <jeffery.to@gmail.com>

1 files changed, 40 insertions, 4 deletions

diff --git a/lang/python/README.md b/lang/python/README.md
index fee9ee31a..fb9a8d230 100644
--- a/lang/python/README.md
+++ b/lang/python/README.md
@@ -1,12 +1,16 @@
 # Python packages folder
 
+:warning: **Python 2 will soon be unsupported and removed from the feed - [see below](#python-2-end-of-life)** :warning:
+
 ## Table of contents
 
 1. [Description](#description)
-2. [Introduction](#introduction)
-3. [Build considerations](#build-considerations)
-4. [General folder structure](#general-folder-structure)
-5. [Building a Python[3] package](#building-a-python3-package)
+2. [Python 2 end-of-life](#python-2-end-of-life)
+    1. [Transition policy / schedule](#transition-policy--schedule)
+3. [Introduction](#introduction)
+4. [Build considerations](#build-considerations)
+5. [General folder structure](#general-folder-structure)
+6. [Building a Python[3] package](#building-a-python3-package)
     1. [PKG_BUILD_DIR](#pkg_build_dir)
     2. [PKG_UNPACK](#pkg_unpack)
     3. [Include python[3]-package.mk](#include-python3-packagemk)
@@ -21,6 +25,38 @@ This section describes specifics for the Python packages that are present in thi
 
 In terms of license, contributing guide, etc, all of that information is described in the top [README.md](README.md) file, and it applies here as well. This document attempts to cover only technical aspects of Python/Python3 packages, and maybe some explanations about how things are (and why they are as they are).
 
+## Python 2 end-of-life
+
+Python 2 will not be maintained past [1 January 2020](https://pythonclock.org/). As such, we will be transitioning Python 2 programs and libraries to Python 3, and Python 2 packages will be removed in early 2020.
+
+(Discussion for how to handle this transition can be found in [#8520](https://github.com/openwrt/packages/issues/8520).)
+
+### Transition policy / schedule
+
+A mass removal event ("The Snap") will occur on 31 March 2020, or 2 weeks before the freeze for a 20.x release, whichever is sooner. The exact date will be confirmed when the 20.x release schedule is known, or by 15 March 2020.
+
+All Python 2 packages (the Python 2 interpreter, programs that depend on Python 2, and Python 2-only libraries) will be removed during this event.
+
+Leading up to "The Snap":
+
+* In general, new Python 2 packages are no longer accepted
+  * Exceptions can be made on a case-by-case basis, given extraordinary circumstances or reasons, until 31 May 2019
+  * From 31 May 2019 onward, absolutely no new Python 2 packages will be accepted
+
+* The Python 2 interpreter will remain in the feed until "The Snap"
+  * The interpreter will continue to be updated, including the last release in January 2020 (if there is one)
+
+* Programs that depend on Python 2 will be transitioned to Python 3 (see [#8893](https://github.com/openwrt/packages/issues/8893))
+  * If a program cannot be transitioned, a suitable replacement will be found
+  * If a replacement cannot be found, the program will be removed during "The Snap"
+
+* Python 2 libraries will remain in the feed until "The Snap"
+  * A Python 2-only library will be transitioned to Python 3 (or a suitable replacement found), if its Python 3 version is a dependency of another package in the feed
+  * Python 2 libraries will receive normal updates until 31 October 2019
+  * From 31 October 2019 onward:
+    * Python 2-only libraries will receive security updates only
+    * Python 2 libraries that share the same Makefile as their Python 3 version will continue to receive normal updates
+
 ## Introduction
 
 This sub-tree came to exist after a number of contributions (Python packages) were made to this repo, and the [lang](lang) subtree grew to a point where a decision was made to move all Python packages under [lang/python](lang/python).