Skip to content

Commit 87e88be

Browse files
committed
docs(standard): require a floors job that resolves the declared dependency floors
1 parent 54fd3de commit 87e88be

1 file changed

Lines changed: 27 additions & 2 deletions

File tree

‎docs/standard.md‎

Lines changed: 27 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -100,8 +100,9 @@ environment, generated code).
100100

101101
## 6. Python versions
102102

103-
There is no floor policy. A repo sets `requires-python` to what its code needs and may raise it
104-
without a recorded reason.
103+
There is no floor policy for Python itself. A repo sets `requires-python` to what its code needs
104+
and may raise it without a recorded reason. A dependency floor is a separate obligation, carried by
105+
section 7.
105106

106107
The obligation is at the other end: **the test matrix always includes the newest stable CPython
107108
minor and that minor's free-threaded build** (`3.14` and `3.14t` today). The matrix is every minor
@@ -126,9 +127,33 @@ Both call the repo's own reusable `_checks.yml`, which has these jobs:
126127
|---|---|
127128
| `lint` | `just install lint-ci` on the repo's floor Python |
128129
| `pytest` | `just install` then `just test-ci` on every matrix entry, `fail-fast: false` |
130+
| `floors` | every direct dependency resolved at its declared floor, wheel-only, on every matrix entry, then the suite or an import |
129131
| `links` | [lychee](https://github.com/lycheeverse/lychee-action) with `--offline`, remapping this repo's `blob/main` URLs to the checkout, so it fails only on a relative link or file path the diff broke |
130132
| `docs` | `just docs-build` (`mkdocs build --strict`), only for repos with a docs site |
131133

134+
A declared dependency floor is a claim that the package installs and works against that version,
135+
and `floors` is the only job that tests it: `pytest` resolves every dependency at its newest, so
136+
the bottom of each declared range otherwise ships unexercised. It rots there. `compose2pod` shipped
137+
a PyYAML floor that could not install on 3.14
138+
([compose2pod#126](https://github.com/modern-python/compose2pod/issues/126)), and
139+
`faststream-outbox` shipped a `pydantic>=2` floor that no `cp313` wheel satisfies below pydantic
140+
2.8.1 ([faststream-outbox#190](https://github.com/modern-python/faststream-outbox/pull/190)).
141+
142+
Two properties of the job are not optional. **Wheel-only** (`--no-build`, or `--only-binary` naming
143+
the dependency that needs it): a floor reachable only by compiling an sdist is not a floor a user
144+
installing a wheel can reach, and without the flag the resolver builds one and reports success.
145+
**Every matrix entry**: wheel coverage is per interpreter, so two interpreters that resolve the
146+
same versions can still disagree on whether those versions install, which is what a marked floor
147+
(`python_version == '3.13'`) exists to say.
148+
149+
The rest is the repo's call. Run the full suite at the floors where they can carry it and an import
150+
smoke test where they cannot; drop a matrix entry no upstream wheel covers, as `compose2pod` drops
151+
`3.14t` for PyYAML. Like every other job, `floors` runs from both `ci.yml` and `scheduled.yml`.
152+
Resolving direct dependencies low and transitive ones high does expose it to an upstream release
153+
that no pull request caused, but that is not a difference in kind: `install` upgrades the lockfile
154+
(section 2), so `pytest` resolves fresh on every run too, and the org already accepts that exposure
155+
on a pull request.
156+
132157
`_checks.yml` is per repo by decision, not by omission. A shared workflow in `modern-python/.github`
133158
was built and proven
134159
([#95](https://github.com/modern-python/.github/issues/95)), and rejected on its interface: a

0 commit comments

Comments
 (0)