From 0cb929de5bb7644f5db5e4cf14cffb4b07f003ae Mon Sep 17 00:00:00 2001 From: Ramesh Padmanabhaiah Date: Sat, 20 Jun 2026 17:46:11 -0700 Subject: [PATCH] Document uv migration paths --- .ai-context/DECISIONS.md | 3 +++ docs/README.md | 4 ++-- docs/python-manifest.md | 49 ++++++++++++++++++++++++++++++++++++++++ 3 files changed, 54 insertions(+), 2 deletions(-) diff --git a/.ai-context/DECISIONS.md b/.ai-context/DECISIONS.md index 535a3e8d..64105007 100644 --- a/.ai-context/DECISIONS.md +++ b/.ai-context/DECISIONS.md @@ -50,6 +50,9 @@ architecture discussion. - uv support is explicit: `python.manager: uv` opts a project into uv-managed setup and `.venv` ownership, while command-level `runner: uv` is independent and may be used in composite projects. +- uv adoption cleanup is manual: when a project moves from Base-managed Python + to `python.manager: uv`, Base ignores stale `~/.base.d//.venv` + directories but does not delete them automatically. - Build tool provisioning should be profile-driven or project-declared, not hardcoded inside `basectl build`. - New tool families such as AI developer tools should stay explicit and diff --git a/docs/README.md b/docs/README.md index e688c7af..654d9dbc 100644 --- a/docs/README.md +++ b/docs/README.md @@ -85,8 +85,8 @@ reference. The filename should answer "what is this about?" installers should use Base without moving product-specific logic into Base. - [Artifact Adapter Registry](artifact-adapter-registry.md) designs the declarative registry and adapter boundary for Base-managed artifacts. -- [Python Manifest Section](python-manifest.md) records the future structured - Python manifest shape and its relationship to current `python-package` +- [Python Manifest Section](python-manifest.md) records the structured Python + manifest shape, uv adoption paths, and its relationship to `python-package` artifacts. - [Repository Baseline](repo-baseline.md) documents `basectl repo init`, `basectl repo check`, `basectl repo configure`, and the optional diff --git a/docs/python-manifest.md b/docs/python-manifest.md index 1117bae1..e271c22e 100644 --- a/docs/python-manifest.md +++ b/docs/python-manifest.md @@ -34,6 +34,55 @@ environment as the project virtual environment: /.venv ``` +## Migration Paths + +### Base-Managed Project Adopts uv + +For a project that already uses Base's historical project virtual environment, +add the explicit uv contract to `base_manifest.yaml`: + +```yaml +python: + manager: uv +``` + +Move Python dependencies into `pyproject.toml`, create or refresh `uv.lock` with +uv, and run `uv sync` or `basectl setup ` from the project root. After +that, `basectl activate`, `basectl run`, `basectl test`, `basectl build`, and +`basectl demo` use `/.venv` as the project environment unless the +caller explicitly sets `BASE_PROJECT_VENV_DIR`. + +If the old Base-managed environment still exists at +`~/.base.d//.venv`, Base reports it as stale and ignores it. Base does +not delete that directory automatically because it may contain local state, +debugging context, or artifacts a user still wants. Once `basectl check +` reports the uv project virtual environment as healthy, users may +remove the stale Base-managed project environment manually if they no longer +need it. + +### Existing uv Project Adopts Base + +For an existing uv project, keep `pyproject.toml`, `uv.lock`, and the repo-local +`.venv` under uv ownership. Add a small Base manifest that opts into uv-managed +Python: + +```yaml +project: + name: example + +python: + manager: uv +``` + +Run `basectl setup ` to let Base delegate Python setup to `uv sync`. +Add `runner: uv` only for manifest commands that should execute through +`uv run -- ...`; command runner selection is independent from +`python.manager: uv`. + +Base does not infer uv ownership from `pyproject.toml` or `uv.lock` alone. The +manifest opt-in is what lets Base choose the repo-local `.venv` and report uv +diagnostics. + ## Command Runners Command execution is independent from the project-level Python manager. Any