Debian Codegraph @

.claude/commands/update-python-version.md

raw
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