From 86be220e7d8f7e3a915b27f6b4bb69b15418b4cf Mon Sep 17 00:00:00 2001 From: Mason Daugherty Date: Wed, 3 Jun 2026 16:45:58 -0400 Subject: [PATCH] docs(infra): document uv-based Python environment setup (#37881) Adds an "Environment and dependency management" subsection to the contributor guidance files, codifying the existing `uv`-only workflow so agents and contributors don't reach for `pip`/`poetry`/`conda`, pin a global Python version, or spin up stray virtualenvs. The guidance is adapted to the monorepo's reality (per-package `requires-python`, `uv sync`/`uv run` without manual activation) rather than a generic single-project setup. --- AGENTS.md | 9 +++++++++ CLAUDE.md | 9 +++++++++ 2 files changed, 18 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 09d0564f28a..8e3de8d5c58 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -73,6 +73,15 @@ make format uv run --group lint mypy . ``` +#### Environment and dependency management + +Use `uv` for all environment and dependency operations in this monorepo. Do not invoke `pip`, `poetry`, or `conda` directly. + +- Let `uv` manage the interpreter and virtual environments — `uv sync` and `uv run` operate without manual `source .venv/bin/activate`. Do not create ad-hoc virtual environments outside the package directory. +- Each package targets its own supported Python range via its `pyproject.toml`; do not pin a global Python version. If you need an interpreter explicitly, defer to the package's `requires-python` rather than assuming system Python. +- Install dependencies explicitly through `uv sync` (optionally `--group ` / `--all-groups`); never let them install implicitly. +- Don't mix environments within a session, and don't add new dependencies unless strictly required — when you do, justify them (recent releases/commits, adoption). + #### Key config files - pyproject.toml: Main workspace configuration with dependency groups diff --git a/CLAUDE.md b/CLAUDE.md index 09d0564f28a..8e3de8d5c58 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -73,6 +73,15 @@ make format uv run --group lint mypy . ``` +#### Environment and dependency management + +Use `uv` for all environment and dependency operations in this monorepo. Do not invoke `pip`, `poetry`, or `conda` directly. + +- Let `uv` manage the interpreter and virtual environments — `uv sync` and `uv run` operate without manual `source .venv/bin/activate`. Do not create ad-hoc virtual environments outside the package directory. +- Each package targets its own supported Python range via its `pyproject.toml`; do not pin a global Python version. If you need an interpreter explicitly, defer to the package's `requires-python` rather than assuming system Python. +- Install dependencies explicitly through `uv sync` (optionally `--group ` / `--all-groups`); never let them install implicitly. +- Don't mix environments within a session, and don't add new dependencies unless strictly required — when you do, justify them (recent releases/commits, adoption). + #### Key config files - pyproject.toml: Main workspace configuration with dependency groups