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..ee54339d --- /dev/null +++ b/doc/dev/bumping-python.md @@ -0,0 +1,88 @@ +# 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. + + +## 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 | +| `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 + +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 . +flake8 -v +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 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. 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 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