Skip to content

AGENTS.md

Latest commit

 

History

History
71 lines (58 loc) · 2.93 KB

AGENTS.md

File metadata and controls

71 lines (58 loc) · 2.93 KB
Raw

Repository Guidance

Generated SDK

Most SDK source is generated by Stainless. Follow CONTRIBUTING.md before changing generated files. Handwritten policy, automation, tests, and examples should remain small and should not alter exported SDK APIs unless the change explicitly requires it.

Python version policy

  • requires-python in pyproject.toml is the authoritative technical minimum.
  • PYTHON_VERSION_POLICY.md is the human-readable support and release policy.
  • Support every fully released, non-EOL CPython line. A documented grace period may temporarily add the most recently retired line.
  • Keep requires-python, classifiers, dependency markers, README requirements, static-analysis targets, .python-version, and CI synchronized.
  • Do not combine a minimum-Python change with unrelated SDK or dependency upgrades.

Changing the minimum Python version

  1. Update pyproject.toml, .python-version, the lock files, README, CONTRIBUTING.md, and PYTHON_VERSION_POLICY.md.
  2. Remove dependency branches that only served the retired runtime.
  3. Update minimum/current and full-matrix CI coverage.
  4. Build both distributions and validate their Requires-Python metadata and old-interpreter rejection behavior.
  5. Add a ## Release note section to the pull request description naming the new minimum and final compatible SDK release. Do not promise security backports for the old release.
  6. Obtain SDK CODEOWNER approval.

The deterministic Python policy check proves repository surfaces agree. It does not decide whether an EOL grace period or floor increase is appropriate.

Automation map

  • .github/workflows/ci.yml
    • On pull requests and branch pushes: lint, build, metadata validation, and tests on the minimum and current stable Python releases.
    • Nightly and manually: smoke-tests every supported Python release and the allowed-failure prerelease.
  • .github/workflows/python-version-review.yml
    • Monthly on the default branch: snapshots official CPython lifecycle data plus the public PyPI Python-minor distribution and asks Codex for a policy review.
    • Runs a pinned Codex runtime as an unprivileged user with no command network access and read-only repository permissions.
    • Codex cannot edit the repository or call GitHub. A separate job with no OpenAI credential opens or refreshes one issue only when action is needed.
    • Never changes the Python floor or merges code automatically.

Validation

Before publishing a Python-version change, run:

rye lock --all-features
uv lock --check
rye build
rye run python scripts/check-python-version-policy.py
rye run python scripts/utils/validate-python-version-wheel.py
python3.9 scripts/utils/validate-python-version-wheel.py --check-python-39
rye run python scripts/utils/validate-bedrock-wheel.py
rye run python scripts/utils/validate-httpx2-wheel.py
./scripts/lint
./scripts/test

Also run the scheduled compatibility matrix before release.