From d4ca537f21501795f404fa31dc29110d6c8e2114 Mon Sep 17 00:00:00 2001 From: Kyle McCormick Date: Tue, 30 Apr 2024 13:36:37 -0400 Subject: [PATCH] docs: add upgrade details to edx-sandbox readme (#34632) --- requirements/edx-sandbox/README.rst | 79 ++++++++++++++++++----------- 1 file changed, 48 insertions(+), 31 deletions(-) diff --git a/requirements/edx-sandbox/README.rst b/requirements/edx-sandbox/README.rst index 6129aa865b31..d2118761769c 100644 --- a/requirements/edx-sandbox/README.rst +++ b/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