| 1 |
--- |
| 2 |
description: Update the minimum Python version requirement across the entire codebase |
| 3 |
--- |
| 4 |
|
| 5 |
# Update Python Version Command |
| 6 |
|
| 7 |
You are tasked with updating the minimum Python version requirement across the entire codebase. |
| 8 |
|
| 9 |
## Input |
| 10 |
|
| 11 |
The user will provide the new minimum Python version in the format "3.X" (e.g., "3.14", "3.15"). |
| 12 |
|
| 13 |
## Steps to Execute |
| 14 |
|
| 15 |
### 1. Validate Input |
| 16 |
- Ensure the provided version is in the correct format (e.g., "3.14") |
| 17 |
- Extract the old version from `pyproject.toml` by reading the `requires-python` field |
| 18 |
|
| 19 |
### 2. Search for All References |
| 20 |
Search for all occurrences of the old Python version across the codebase. You must check at the very least: |
| 21 |
- `pyproject.toml` - `requires-python` field |
| 22 |
- `.readthedocs.yml` - Python version specification |
| 23 |
- `.github/workflows/*.yaml` - Python version matrices and specifications |
| 24 |
- `README.md` - Badge and requirements sections |
| 25 |
- `docs/index.md` - Badge and requirements sections |
| 26 |
- `docs/getting-started/installation.md` - Requirements section |
| 27 |
- `docs/development/contributing.md` - Prerequisites section |
| 28 |
- `docs/development/architecture.md` - Type hints references |
| 29 |
- `CLAUDE.md` - Any version references |
| 30 |
|
| 31 |
Use Grep to search for patterns like: |
| 32 |
- The old version number (e.g., "3.13") |
| 33 |
- Badge URLs containing the version (e.g., "python-3.13%2B") |
| 34 |
- Version specifications in YAML files |
| 35 |
|
| 36 |
### 3. Update All Files |
| 37 |
Update ALL occurrences of the old version to the new version: |
| 38 |
|
| 39 |
#### pyproject.toml |
| 40 |
- Update `requires-python = ">=X.Y"` to the new version |
| 41 |
- Update classifier `"Programming Language :: Python :: X.Y"` if present |
| 42 |
- Note: This may trigger `uv.lock` regeneration |
| 43 |
|
| 44 |
#### .readthedocs.yml |
| 45 |
- Update `python: "X.Y"` to the new version |
| 46 |
|
| 47 |
#### .github/workflows/*.yaml |
| 48 |
- Update Python version matrices (e.g., `python-version: ["X.Y", ...]`) |
| 49 |
- Add new version, potentially remove old unsupported versions |
| 50 |
|
| 51 |
#### Documentation Files |
| 52 |
- Update badges from `python-X.Y%2B` to `python-X.Z%2B` |
| 53 |
- Update requirements text from "Python X.Y or higher" to "Python X.Z or higher" |
| 54 |
- Update any other references (e.g., "(3.Y+)" to "(3.Z+)") |
| 55 |
|
| 56 |
### 4. Regenerate Lock File |
| 57 |
After updating `pyproject.toml`, regenerate the lock file: |
| 58 |
```bash |
| 59 |
uv sync --all-extras --group dev --group test --group docs |
| 60 |
``` |
| 61 |
|
| 62 |
### 5. Run Quality Checks |
| 63 |
Execute all quality checks to ensure nothing broke: |
| 64 |
|
| 65 |
```bash |
| 66 |
# Run linting and formatting |
| 67 |
uv run pre-commit run --all-files |
| 68 |
|
| 69 |
# Run type checking |
| 70 |
uv run mypy src/ |
| 71 |
|
| 72 |
# Run tests |
| 73 |
uv run pytest |
| 74 |
``` |
| 75 |
|
| 76 |
### 6. Verify No Remaining References |
| 77 |
After all updates, search again for the old version to ensure no references were missed: |
| 78 |
```bash |
| 79 |
grep -r "X.Y" . --exclude-dir=.git --exclude-dir=.venv --exclude="*.lock" |
| 80 |
``` |
| 81 |
|
| 82 |
Review any remaining occurrences to determine if they need updating or are false positives. |
| 83 |
|
| 84 |
### 7. Summary Report |
| 85 |
Provide a summary of: |
| 86 |
- All files that were updated |
| 87 |
- The specific changes made in each file |
| 88 |
- Test results and whether all checks passed |
| 89 |
- Any remaining references to the old version (with explanation if they're false positives) |
| 90 |
|
| 91 |
## Error Handling |
| 92 |
|
| 93 |
If any step fails: |
| 94 |
1. Report the failure clearly |
| 95 |
2. Do not proceed to subsequent steps |
| 96 |
3. Provide guidance on how to fix the issue |
| 97 |
|
| 98 |
## Notes |
| 99 |
|
| 100 |
- Always use exact string matching when replacing versions to avoid false positives |
| 101 |
- Be careful with version strings that appear in git history or lock files |
| 102 |
- Ensure all badge URLs are properly URL-encoded (use %2B for +) |
| 103 |
- The command should be idempotent - running it multiple times should be safe |