docs: add how-to for managing a uv dependency version matrix (#1436)

* docs: add how-to for managing a uv dependency version matrix

Explains how to add, update, and retire dependencies tested against
multiple versions (e.g. Django 5.x and 6.x) using uv's conflicts
feature with uv-venv-lock-runner in tox.

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

* temp: Apply suggestions from code review

Co-authored-by: Feanil Patel <feanil@axim.org>

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: feanil

source/developers/how-tos/manage-uv-dependency-matrix.rst

@@ -0,0 +1,182 @@
+How To Manage a uv Dependency Version Matrix
+#############################################
+
+.. tags:: developer, how-to
+
+This how-to explains how to add, update, or retire a dependency that is tested
+against multiple versions (e.g. Django 5.x *and* 6.x) in a repository that uses
+``uv`` for dependency management.
+
+Assumptions
+***********
+
+* Your repository uses ``uv``, ``tox-uv``, and ``uv-venv-lock-runner`` for
+  dependency management and testing. If it does not, see the
+  `uv ADR in openedx-proposals`_ for background on the expected setup.
+
+* You understand
+  `PEP 735 dependency groups`_ and how ``[tool.uv].conflicts`` lets ``uv``
+  produce a single ``uv.lock`` with independent resolutions for mutually
+  exclusive groups.
+
+.. _uv ADR in openedx-proposals: https://docs.openedx.org/projects/openedx-proposals/en/latest/best-practices/oep-0067/decisions/backend/0001-uv.html
+.. _PEP 735 dependency groups: https://peps.python.org/pep-0735/
+
+Steps: Adding a new version
+****************************
+
+Use this process when you want to start testing against a new version while
+still keeping the previous one in the matrix (e.g. add Django 6.0 while still
+testing Django 5.2).
+
+The ``test`` group always represents the **current default version** — the one
+used by quality checks, docs builds, and the primary CI matrix entry. When
+promoting a new version to default, the old version moves to its own named
+group (e.g. ``django52``).
+
+1. **Update the** ``test`` **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** so ``uv`` knows the groups are mutually exclusive:
+
+   .. code-block:: toml
+
+      [tool.uv]
+      conflicts = [
+          [
+              {group = "test"},
+              {group = "django52"},  # new
+          ],
+      ]
+
+   Add the new group to the existing conflict entry — all version groups for
+   the same dependency belong in a single list.
+
+4. **Update** ``tox.ini`` — add the new legacy factor to ``envlist`` and a
+   factor conditional to ``dependency_groups``:
+
+   .. code-block:: ini
+
+      # Before
+      [tox]
+      envlist = py312-django{52},quality,docs
+
+      [testenv]
+      runner = uv-venv-lock-runner
+      dependency_groups =
+          django52: test
+
+      # After
+      [tox]
+      envlist = py312-django{52,60},quality,docs
+
+      [testenv]
+      runner = uv-venv-lock-runner
+      dependency_groups =
+          django52: django52
+          django60: test
+
+5. **If the new version requires overriding a global constraint** (for example,
+   the global edx-lint constraint pins ``Django<6.0`` but you need ``Django<7.0``
+   to allow 6.x to resolve), add an override to ``[tool.edx_lint].uv_constraints``
+   in ``pyproject.toml``:
+
+   .. code-block:: toml
+
+      [tool.edx_lint]
+      uv_constraints = [
+          "Django<7.0",  # allows Django 6.x; overrides the global Django<6.0 pin
+      ]
+
+6. **Regenerate the lockfile**:
+
+   .. code-block:: bash
+
+      make upgrade
+
+Steps: Retiring a version
+**************************
+
+Use this process when a version reaches end-of-life and you want to drop it
+from the matrix entirely.
+
+1. **Remove the legacy group** (e.g. ``django52``) from ``[dependency-groups]``
+   in ``pyproject.toml``.
+
+2. **Remove it from the** ``conflicts`` **list** in ``[tool.uv]``:
+
+   .. code-block:: toml
+
+      [tool.uv]
+      conflicts = [
+          [
+              {group = "test"},
+              {group = "django60"},
+          ],
+      ]
+
+3. **Remove the factor conditional** from ``dependency_groups`` in ``tox.ini``
+   and drop it from ``envlist``:
+
+   .. code-block:: ini
+
+      # Before
+      [tox]
+      envlist = py312-django{52,60},quality,docs
+
+      [testenv]
+      runner = uv-venv-lock-runner
+      dependency_groups =
+          django52: django52
+          django60: test
+
+      # After
+      [tox]
+      envlist = py312-django{60},quality,docs
+
+      [testenv]
+      runner = uv-venv-lock-runner
+      dependency_groups =
+          django60: test
+
+4. **Regenerate the lockfile**:
+
+   .. code-block:: bash
+
+      make upgrade
+
+**Maintenance chart**
+
+.. list-table::
+   :header-rows: 1
+
+   * - Review Date
+     - Working Group Reviewer
+     - Release
+     - Test situation
+   * - 2026-04-27
+     - @feanil
+     - main
+     - Pass