Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion .claude/skills/managing-dependencies/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ The convention resolves this without dropping old-Python support: pin each inter

## File-layout convention

Each file starts with a `# pip install -r requirements/<file>.txt` header, then lists **one dependency per section**: the name of the dependency (as a `# name` header), an optional rationale note (starting with `# Note:`, explaining why a version is pinned or split), then the requirement line(s), separated from the next section by a blank line. This makes every pin self-documenting.
Each file starts with a `# pip install -r requirements/<file>.txt` header, then lists **one dependency per section**: the name of the dependency (as a `# name` header), an **extremely optional** rationale note (starting with `# Note:` — see below), then the requirement line(s), separated from the next section by a blank line. This makes every pin self-documenting.

```
# pip install -r requirements/test.txt
Expand All @@ -34,6 +34,8 @@ pytest-cov>=7.1.0,<8; python_version >= "3.14"

Keep this layout when adding or editing dependencies. Never leave an empty trailing `;` (a fossil of a collapsed split; delete it — the old `pytest-asyncio<2;` line was exactly this).

**On the `# Note:` — omit it by default.** The requirement lines and their `python_version` markers already state *what* is pinned and *which interpreter gets which release*, and this skill already establishes that an old-side ceiling marks a floor jump. A note must never restate any of that. Write one only to record rationale the lines cannot express on their own — a non-obvious cap, or a coupling invisible from the specifier. The archetype is the `tracerite` pin (see "a coupled companion dependency" below): a companion dependency that breaks with no `requires_python` metadata, which no reader could infer from the line itself. A routine floor-jump split (like `chalice`, `fastapi`, or `starlette`) needs no note at all. Several older sections still carry notes that merely restate their lines; treat those as legacy, not a template to copy.

## Which files need Python-version markers

A marker split is only needed for requirements files installed across the **full** Python matrix. Which file you are editing decides this. To see where a file is installed, read `.github/workflows/ci-build.yml`. It is the source of truth for which Python versions install which requirements files. Everything except `dev_tools.txt` is installed by the `unittest` matrix job across 3.7–3.14.
Expand Down
4 changes: 2 additions & 2 deletions requirements/adapter_dev.txt
Original file line number Diff line number Diff line change
Expand Up @@ -64,9 +64,9 @@ sanic>=25.3.0,<25.12.0; python_version >= "3.9" and python_version < "3.10"
sanic>=25.12.1,<26; python_version >= "3.10"

# starlette
# Note: starlette 0.49.3 requires Python >=3.9; 3.7/3.8 stay on the older pinned release.
starlette>=0.19.1,<0.45; python_version < "3.9"
starlette>=0.49.3,<1; python_version >= "3.9"
starlette>=0.49.3,<0.50; python_version >= "3.9" and python_version < "3.10"
starlette>=1.6.0,<2; python_version >= "3.10"

# tornado
# Note: tornado 6.5.6 requires Python >=3.9; 3.7/3.8 stay on the older pinned release.
Expand Down