docs: add upgrade details to edx-sandbox readme (openedx#34632)

requirements/edx-sandbox/README.rst

@@ -13,47 +13,64 @@ Files in this directory
 base.in
 =======
 
-This is the current set of requirements or the edx-sandbox
-environment, and it is used to generate the ``.txt`` files described below.
-These requirements share some constraints with the general edx-platform
-requirements (via ``../constraints.txt``), but otherwise, they are completely
-separate.
+This is the current set of requirements or the edx-sandbox environment, and it
+is used to generate the ``.txt`` files described below. These requirements
+share some constraints with the general edx-platform requirements (via
+``../constraints.txt``), but otherwise, they are completely separate.
 
-We do not recommend installing from this file directly, because
-the packages are not pinned.
+Installing the edx-sandbox environment from this file is **unsupported** and
+**unstable**, because the packages are not pinned.
 
 base.txt
 ========
 
-These are the latest requirement pins for edx-sandbox.
-They are regularly updated with the latest compatible versions of each package.
+These are the latest requirement pins for edx-sandbox. They are regularly
+updated with the latest compatible versions of each package.
 
-Install from this file if you wish to always run the latest edx-sandbox
-environment. Take note that there will periodically be breaking changes to
-``base.txt``. For example, we may update the Python version used to generate
-the pins, which may break edx-sandbox environments running older Python
-versions.
+Installing the edx-sandbox environment from this file is **supported** yet
+**unstable**. Breaking package upgrades and Python langugae upgrades will
+regularly land directly in base.txt.
 
-releases/(RELEASE_NAME).txt
-===========================
-
-*e.g. releases/redwood.txt, releases/sumac.txt, etc.*
+releases/
+=========
 
 Starting with Quince, every named Open edX release adds one of these files.
-They contain the requirement pins corresponding to ``base.txt`` at the time
-of each release.
+They contain the requirement pins corresponding to ``base.txt`` at the time of
+each release.
+
+Installing the edx-sandbox environment from the *latest* release file is
+**supported** and **stable**. Installing the edx-sandbox environment from
+*older* release files is **unsupported** yet **stable**.
+
+When migrating from one release file to a newer one, be aware of which Python
+versions are supported as well as breaking changes in newer packages versions.
+You may need to edit the instructor-authored Python code in your platform in
+order for it to remain compatible. The edx-platform maintenance team will do their
+best to make note of these changes below and in the Open edX release notes.
+
+releases/quince.txt
+-------------------
+
+* Frozen between the Quince and Redwood releases
+* Supports only Python 3.8
+
+releases/redwood.txt (FUTURE PLAN)
+----------------------------------
 
-Install from one of these files if you want to run a stable edx-sandbox
-environment without breaking changes.
+* Frozen at the time of the Redwood release
+* Supports Python 3.8 and Python 3.11
+* BREAKING CHANGE: SciPy is upgraded from 1.7.3 to 1.10.1 (`SciPy changelog`_)
+* BREAKING CHANGE: NumPy is upgraded from 1.22.4 to 1.24.4
+  (`NumPy changelog`_)
+* These upgrades prepare edx-sandbox for the Python 3.12 update in Sumac.
 
-Support windows
-***************
+releases/sumac.txt (FUTURE PLAN)
+--------------------------------
 
-Only ``base.txt`` and the latest ``release/*.txt`` from the latest named
-release are supported by the Open edX community. However, we will leave
-old ``release/*.txt`` files in the repository to assist:
+* Frozen at the time of the Sumac release
+* BREAKING CHANGE: Drops support for Python 3.8 (`Python changelog`_)
+* Supports Python 3.11 and Python 3.12
 
-* operators who want to stagger their edx-sandbox upgrade from their general
-  edx-platform upgrade
-* operators who need to temporarily roll back their edx-sandbox environments
-  so that instructors can fix their loncapa Python code.
+.. _Python changelog: https://docs.python.org/3.11/whatsnew/changelog.html
+.. _SciPy changelog: https://docs.scipy.org/doc/scipy/release.html
+.. _NumPy changelog: https://numpy.org/doc/stable/release.html