feat: update tox.ini to use tox-uv with locked dependency groups

Adds tox-uv>=1 to [tox].requires. Switches all testenv sections to
uv-venv-lock-runner so every run installs exactly from uv.lock.

For the Django version matrix, splits test-base (framework-agnostic
pytest deps) from test (test-base + current Django 5.2). The django42
group holds the legacy Django 4.2 pin. Declaring these groups as
conflicting in [tool.uv].conflicts lets uv produce a single uv.lock
with a separate resolution per group. Tox factor conditionals select
the right group per environment.

Adds docs/how-tos/adding-a-matrix-dependency.rst explaining how to add
or retire a version from any dependency matrix.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: feanil

backend/docs/how-tos/adding-a-matrix-dependency.rst

@@ -0,0 +1,96 @@
+.. _how-to-matrix-dependency:
+
+Adding or Updating a Matrix Dependency Version
+###############################################
+
+This project tests against multiple versions of certain dependencies (e.g.
+Django). Each version in the matrix gets its own ``[dependency-groups]`` entry
+in ``pyproject.toml``, and ``uv`` produces a single ``uv.lock`` with a separate
+resolution per group via the ``[tool.uv].conflicts`` feature.
+
+The ``test`` group always represents the **current default version** — the one
+used by quality checks, docs builds, and the primary CI matrix entry. Legacy
+versions get their own named groups (e.g. ``django42``).
+
+How it works
+************
+
+``uv`` normally requires all dependency groups to resolve to a compatible set of
+packages. Declaring groups as conflicting tells ``uv`` they are mutually
+exclusive — it produces a single ``uv.lock`` with independent resolutions for
+each group. ``tox`` then selects the right group per environment via factor
+conditionals, and ``uv-venv-lock-runner`` installs from the lockfile so every
+run is fully reproducible.
+
+Adding support for a new version
+*********************************
+
+Use this process when you want to **add a new version** to the test matrix
+(e.g. start testing against Django 6.0 while still supporting Django 5.2).
+
+1. **Update the default group** in ``pyproject.toml`` to the new version:
+
+   .. code-block:: toml
+
+       # Before
+       test = [
+           {include-group = "test-base"},
+           "Django>=5.0,<6.0",
+       ]
+
+       # After
+       test = [
+           {include-group = "test-base"},
+           "Django>=6.0,<7.0",
+       ]
+
+2. **Add a legacy group** for the version being retained:
+
+   .. code-block:: toml
+
+       django52 = [
+           {include-group = "test-base"},
+           "Django>=5.0,<6.0",
+       ]
+
+3. **Register the conflict** in ``[tool.uv]`` so ``uv`` knows the groups are
+   mutually exclusive:
+
+   .. code-block:: toml
+
+       [tool.uv]
+       conflicts = [
+           [{group = "test"}, {group = "django42"}, {group = "django52"}],
+       ]
+
+4. **Add a tox factor** for the new legacy version. Update ``envlist`` and add
+   a factor conditional to ``dependency_groups``:
+
+   .. code-block:: ini
+
+       [tox]
+       envlist = py{311,312}-django{52,60},docs,quality,pii_check
+
+       [testenv]
+       runner = uv-venv-lock-runner
+       dependency_groups =
+           django42: django42
+           django52: django52
+           django60: test
+
+5. **Regenerate the lockfile**:
+
+   .. code-block:: bash
+
+       make upgrade
+
+Retiring a version
+******************
+
+When a Django version reaches end-of-life and you want to drop it from the
+matrix:
+
+1. Remove the legacy group (e.g. ``django42``) from ``[dependency-groups]``.
+2. Remove it from the ``conflicts`` list in ``[tool.uv]``.
+3. Remove the tox factor conditional line and the envlist entry.
+4. Run ``make upgrade`` to regenerate the lockfile.

backend/docs/how-tos/index.rst

@@ -1,2 +1,7 @@
 How-tos
 #######
+
+.. toctree::
+   :maxdepth: 1
+
+   adding-a-matrix-dependency

backend/pyproject.toml

@@ -47,13 +47,24 @@ Homepage = "https://openedx.org/openedx/sample-plugin"
 Repository = "https://openedx.org/openedx/sample-plugin"
 
 [dependency-groups]
-test = [
+test-base = [
     "pytest-cov",
     "pytest-django",
     "code-annotations",
     "edx-django-utils",
     "django-extensions",
 ]
+# Current default Django version used by quality, docs, and the default test
+# matrix entry. When adding or retiring a Django version from the matrix, see
+# docs/how-tos/adding-a-matrix-dependency.rst for the full process.
+test = [
+    {include-group = "test-base"},
+    "Django>=5.0,<6.0",
+]
+django42 = [
+    {include-group = "test-base"},
+    "Django>=4.0,<5.0",
+]
 quality = [
     {include-group = "test"},
     "edx-lint",
@@ -107,6 +118,13 @@ version_scheme = 'only-version'
 local_scheme = 'no-local-version'
 
 [tool.uv]
+# Each entry lists groups with mutually exclusive version requirements so uv can
+# produce a single uv.lock that contains a separate resolution for each. Add a
+# new pair here whenever you add a legacy-version group to [dependency-groups].
+# See docs/how-tos/adding-a-matrix-dependency.rst for the full process.
+conflicts = [
+    [{group = "test"}, {group = "django42"}],
+]
 #  DO NOT EDIT constraint-dependencies DIRECTLY.
 #  This list is managed by `edx_lint write_uv_constraints`
 #  and will be overwritten the next time `make upgrade` is run.

backend/tox.ini

@@ -1,5 +1,7 @@
 [tox]
-envlist = py{311,312}-django{52},docs,quality,pii_check
+envlist = py{311,312}-django{42,52},docs,quality,pii_check
+requires =
+    tox-uv>=1
 
 [doc8]
 ; D001 = Line too long
@@ -35,15 +37,18 @@ addopts = --cov sample_plugin --cov tests --cov-report term-missing --cov-report
 norecursedirs = .* docs requirements site-packages
 
 [testenv]
-deps =
-    django42: Django>=4.0,<5.0
-    django52: Django>=5.0,<6.0
-    -r{toxinidir}/requirements/test.txt
+runner = uv-venv-lock-runner
+dependency_groups =
+    django42: django42
+    django52: test
 commands =
     pytest {posargs}
     python manage.py check
 
 [testenv:docs]
+runner = uv-venv-lock-runner
+dependency_groups =
+    doc
 setenv =
     DJANGO_SETTINGS_MODULE = test_settings
     PYTHONPATH = {toxinidir}
@@ -52,8 +57,6 @@ setenv =
 allowlist_externals =
     make
     rm
-deps =
-    -r{toxinidir}/requirements/doc.txt
 commands =
     doc8 --ignore-path docs/_build docs
     rm -f docs/sample_plugin.rst
@@ -64,12 +67,13 @@ commands =
     twine check dist/*
 
 [testenv:quality]
+runner = uv-venv-lock-runner
+dependency_groups =
+    quality
 allowlist_externals =
     make
     rm
     touch
-deps =
-    -r{toxinidir}/requirements/quality.txt
 commands =
     touch tests/__init__.py
     pylint sample_plugin tests test_utils manage.py
@@ -80,10 +84,11 @@ commands =
     make selfcheck
 
 [testenv:pii_check]
+runner = uv-venv-lock-runner
+dependency_groups =
+    test
 setenv =
     DJANGO_SETTINGS_MODULE = test_settings
-deps =
-    -r{toxinidir}/requirements/test.txt
 commands =
     code_annotations django_find_annotations --config_file .pii_annotations.yml --lint --report --coverage