From a6c591b5f5bf13c6ac28e377ecde4a4aeba0baa1 Mon Sep 17 00:00:00 2001 From: Ulysses Tiberious Date: Wed, 1 Apr 2026 22:12:54 +0800 Subject: [PATCH 1/4] docs: update README Python prereqs; add dev guides for bumping Python and SymPy (#571) --- README.md | 5 ++- doc/dev/bumping-python.md | 83 ++++++++++++++++++++++++++++++++++++++ doc/dev/bumping-python.rst | 1 + 3 files changed, 87 insertions(+), 2 deletions(-) create mode 100644 doc/dev/bumping-python.md create mode 100644 doc/dev/bumping-python.rst diff --git a/README.md b/README.md index 113efeb9..2e36d273 100644 --- a/README.md +++ b/README.md @@ -202,10 +202,11 @@ Installing GAlgebra ### Prerequisites - Works on Linux, Windows, Mac OSX -- [Python](https://www.python.org/) >= 3.8 +- [Python](https://www.python.org/) >= 3.10 (3.10, 3.11, 3.12 tested via CI) + - 0.6.0 was the last supported release for Python 3.8/3.9 - 0.5.0 was the last supported release for Python 3.5-3.7 - 0.4.x was the last supported release series for Python 2.7 -- [SymPy](https://www.sympy.org) >= 1.3 +- [SymPy](https://www.sympy.org) >= 1.3 - Only SymPy 1.12 is tested via CI, see `.github/workflows/ci.yml` for more details - 0.5.0 was the last supported release for SymPy 1.7 diff --git a/doc/dev/bumping-python.md b/doc/dev/bumping-python.md new file mode 100644 index 00000000..b1a7bb6a --- /dev/null +++ b/doc/dev/bumping-python.md @@ -0,0 +1,83 @@ +# Bumping the Python version support + +This page documents the process for changing the supported Python version +range and explains the policy behind it. + +## Version policy + +- **Drop** Python versions that have reached [end-of-life](https://devguide.python.org/versions/). +- **Add** the most recent minor release that is not the very latest (e.g. add + 3.12 when 3.13 is already out). This keeps us current without chasing + bleeding-edge releases. + +The same "recent but not latest" rule applies to the SymPy version bump; see +[Bumping the SymPy dependency](bumping-sympy.md) for that workflow. + +## Files to update + +| File | What to change | +|------|----------------| +| `.github/workflows/ci.yml` | `python-version` matrix; runner OS; action versions; conditions using a specific version (e.g. `== '3.11'`) | +| `setup.py` | `python_requires`; `Programming Language :: Python :: X.Y` classifiers | +| `README.md` | Prerequisites section Python version line and history note | + +## CI action versions + +When bumping the runner OS (e.g. `ubuntu-22.04` → `ubuntu-24.04`) also audit +the pinned action versions for OS compatibility: + +- `actions/checkout` — bump to latest v4+ +- `actions/setup-python` — bump to latest v5+ +- `actions/cache` — bump to latest v4+ +- `hidakatsuya/action-setup-diff-pdf` — check release notes; v1.4.0 added + Ubuntu 24.04 support + +## Python 3.12 compatibility audit + +Before opening the bump PR, audit the codebase and notebooks for known Python +3.12 breaking changes: + +**`distutils` removed** + +```bash +grep -r "import distutils" . +``` + +Replace with `packaging` (add to `test_requirements.txt` if not present). + +**Unrecognized escape sequences become `SyntaxWarning`** + +In Python 3.12, `'\mathbf'`, `'\grad'`, etc. are `SyntaxWarning` (previously +`DeprecationWarning`). nbval catches the stderr output and fails the cell. + +```bash +python -W error::SyntaxWarning -c "import ast; ast.parse(open('file.py').read())" +``` + +For notebooks, search for unquoted backslash sequences in code cells and add +the `r` prefix: `'\mathbf{e}'` → `r'\mathbf{e}'`. + +## Testing locally + +```bash +uv venv --python 3.12 .venv312 +uv pip install -r test_requirements.txt -e . +python -m flake8 -v +python -m pytest \ + -vv --durations=50 \ + --cov=galgebra \ + --nbval examples/ipython/ \ + --nbval examples/primer/ \ + test \ + --nbval-current-env \ + --nbval-sanitize-with test/.nbval_sanitize.cfg \ + -n 2 --dist loadscope +``` + +## Tracking issue pattern + +Python bumps often uncover several independent blocking issues (compat +failures, notebook output changes). Use the **tracking issue** pattern: one +tracker issue for the overall bump, sub-issues for each blocker, a PR per +sub-issue. See [Bumping the SymPy dependency](bumping-sympy.md) for a +detailed description of this pattern. diff --git a/doc/dev/bumping-python.rst b/doc/dev/bumping-python.rst new file mode 100644 index 00000000..534b3563 --- /dev/null +++ b/doc/dev/bumping-python.rst @@ -0,0 +1 @@ +.. mdinclude:: bumping-python.md From a5d9b830fe2b4c416e4649848f5daccc80f6a5f9 Mon Sep 17 00:00:00 2001 From: Ulysses Tiberious Date: Thu, 2 Apr 2026 09:20:14 +0800 Subject: [PATCH 2/4] docs: address review feedback on #572 - Remove Developer guides toctree from doc/index.rst; #574 owns it with the full three-entry block to avoid duplicate sidebar sections - Fix setup.py: python_requires>=3.10, drop 3.8/3.9 classifiers, add 3.12 - Add test_requirements.txt to the files-to-update table in bumping-python.md --- doc/dev/bumping-python.md | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/dev/bumping-python.md b/doc/dev/bumping-python.md index b1a7bb6a..e0e1dee5 100644 --- a/doc/dev/bumping-python.md +++ b/doc/dev/bumping-python.md @@ -19,6 +19,7 @@ The same "recent but not latest" rule applies to the SymPy version bump; see |------|----------------| | `.github/workflows/ci.yml` | `python-version` matrix; runner OS; action versions; conditions using a specific version (e.g. `== '3.11'`) | | `setup.py` | `python_requires`; `Programming Language :: Python :: X.Y` classifiers | +| `test_requirements.txt` | Add or update compatibility shims (e.g. `packaging` to replace `distutils`) | | `README.md` | Prerequisites section Python version line and history note | ## CI action versions From 414440b379f872a29b3510ee5ad840706ce64ea7 Mon Sep 17 00:00:00 2001 From: Ulysses Tiberious Date: Thu, 2 Apr 2026 10:30:28 +0800 Subject: [PATCH 3/4] docs: add only bumping-python to Developer guides toctree --- doc/index.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/doc/index.rst b/doc/index.rst index 6d693bd6..851f2197 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -33,7 +33,6 @@ dev/release-process dev/bumping-python - dev/bumping-sympy .. toctree:: :caption: Other information From cb8bc51fd9fe7d4d25d1ca6df2142020f8ecbdcf Mon Sep 17 00:00:00 2001 From: Ulysses Tiberious Date: Thu, 2 Apr 2026 12:14:19 +0800 Subject: [PATCH 4/4] docs(bumping-python): make doc self-contained, no sympy cross-refs - Remove version policy cross-reference to bumping-sympy.md - Inline the full tracking issue pattern description instead of deferring to bumping-sympy.md - Use bare flake8/pytest to match CI --- doc/dev/bumping-python.md | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/doc/dev/bumping-python.md b/doc/dev/bumping-python.md index e0e1dee5..ee54339d 100644 --- a/doc/dev/bumping-python.md +++ b/doc/dev/bumping-python.md @@ -10,8 +10,6 @@ range and explains the policy behind it. 3.12 when 3.13 is already out). This keeps us current without chasing bleeding-edge releases. -The same "recent but not latest" rule applies to the SymPy version bump; see -[Bumping the SymPy dependency](bumping-sympy.md) for that workflow. ## Files to update @@ -63,8 +61,8 @@ the `r` prefix: `'\mathbf{e}'` → `r'\mathbf{e}'`. ```bash uv venv --python 3.12 .venv312 uv pip install -r test_requirements.txt -e . -python -m flake8 -v -python -m pytest \ +flake8 -v +pytest \ -vv --durations=50 \ --cov=galgebra \ --nbval examples/ipython/ \ @@ -78,7 +76,13 @@ python -m pytest \ ## Tracking issue pattern Python bumps often uncover several independent blocking issues (compat -failures, notebook output changes). Use the **tracking issue** pattern: one -tracker issue for the overall bump, sub-issues for each blocker, a PR per -sub-issue. See [Bumping the SymPy dependency](bumping-sympy.md) for a -detailed description of this pattern. +failures, notebook output changes). Use the **tracking issue** pattern to +keep each PR small and reviewable: + +1. Open a *tracker* issue describing the overall goal (e.g. "Bump Python to + 3.10–3.12"). Keep it focused on the goal — do not list specific errors. +2. For each blocking problem found during testing, open a *sub-issue* + describing only that problem. +3. Add a comment to the tracker referencing all sub-issues. +4. Open a PR for each sub-issue independently. +5. Once all sub-PRs are merged, open the final bump PR and close the tracker.