docs: clarify how to use the uv plugin
Metadata
Current evaluation
Merged PR #2413 as commit 2154ccbd, fixing #2238: uv examples now install astral-uv, while migration docs clarify runtime dependencies and uv.lock.
Resolution: closed resolved
Reason: PR #2413 was merged into main as commit 2154ccbd. It corrected the uv plugin examples and expanded the migration guidance for dependencies and lock files.
Evaluated by: mr-cal-bot
No scores available.
Issue body
Fixes #2238. In the docs, the examples that show the uv plugin don't work because uv doesn't get installed. This affects [Migrate from the Charm plugin to the uv plugin](https://documentation.ubuntu.com/charmcraft/latest/howto/migrate-plugins/charm-to-uv/) and the example at the end of [uv plugin](https://documentation.ubuntu.com/charmcraft/latest/reference/plugins/uv_plugin/#example).
This PR:
- Adds the `astral-uv` snap to the examples, as we agreed in [#2238](https://github.com/canonical/charmcraft/issues/2238).
- Clarifies/expands the migration guide:
- Adds [List the charm's dependencies](https://canonical-ubuntu-documentation-library--2413.com.readthedocs.build/charmcraft/2413/howto/migrate-plugins/charm-to-uv/#list-the-charm-s-dependencies) to clarify that direct dependencies go in `dependencies` in pyproject.toml.
- Updates [List charm library dependencies](https://canonical-ubuntu-documentation-library--2413.com.readthedocs.build/charmcraft/2413/howto/migrate-plugins/charm-to-uv/#list-charm-library-dependencies) to recommend that dependencies from charmlib `PYDEPS` also go in `dependencies` (because they are runtime dependencies), as discussed in [#2312](https://github.com/canonical/charmcraft/pull/2312). I kept the dependency group approach as an alternative, but de-emphasized it. I also mentioned what to do for Python package libraries.
- Adds [Lock the dependencies](https://canonical-ubuntu-documentation-library--2413.com.readthedocs.build/charmcraft/2413/howto/migrate-plugins/charm-to-uv/#lock-the-dependencies) to be explicit that uv.lock is needed.
Evaluation history
| Date | Model | Scores | Action | Summary |
|---|---|---|---|---|
| stealth/space-bunny-alpha | — | closed resolved | Merged PR #2413 as commit 2154ccbd, fixing #2238: uv examples now install astral-uv, while migration docs clarify runtime dependencies and uv.lock. | |
| stealth/space-bunny-alpha | — | closed resolved | Merged in #2413 (commit 2154ccbd), updating uv plugin and Charm-to-uv migration docs to install astral-uv, explain runtime dependencies, and require uv.lock. | |
| stealth/space-bunny-alpha | — | closed resolved | Merged in PR #2413 (commit 2154ccbd): corrected uv plugin examples with astral-uv installation and expanded migration guidance for dependencies and uv.lock. | |
| qwen/qwen3.6-35b-a3b | — | — | Merged docs clarifying uv plugin usage. Added astral-uv snap to examples and updated the migration guide for dependency placement in pyproject.toml and uv.lock. Approved by four reviewers and passed CI checks. | |
| qwen3.6-35b-a3b-mtp-q6 | — | — | Merged documentation updates fixing broken uv plugin examples by adding the astral-uv snap installation. Clarified the migration guide with explicit dependency listing, charmlib recommendations, and uv.lock instructions. Resolves #2238. |
Update history
No update history recorded yet.
Related work
-
Likely Fixed By:
canonical/charmcraft#2238
(confidence 100%)
PR #2413 fixed the issue by documenting installation of uv through the astral-uv snap.
-
Related To:
canonical/charmcraft#2312
(confidence 95%)
Its treatment of charm-library runtime dependencies informed the updated migration guidance.
Related issues
| Issue | Project | State | Summary | Similarity |
|---|---|---|---|---|
| #1486 docs: update uv plugin reference | craft-parts | merged | Merged PR #1486 as commit f91f0d4c, documenting UV_COMPILE_BYTECODE and correcting minor details in the uv plugin reference. | |
| #2238 uv how-to should include how to install uv in the build environment | charmcraft | closed | Documented installing uv in build environments via the astral-uv snap and clarified uv.lock requirements in PR #2413 (commit 2154ccbd). | |
| #2156 docs(how-to): add how-to migrate to uv | charmcraft | merged | Merged #2156 in commit 7947040c, adding a Charm-to-uv migration guide, a uv-plugin reference cross-link, and a typo fix. | |
| #1580 uv plugin documentation is misleading | craft-parts | closed | Resolved in merged PR #1589 (acfffd36), documenting that uv creates its venv in $CRAFT_PART_INSTALL and advising separate parts for unrelated stage-packages. | |
| #1101 Improve uv plugin doc | craft-parts | merged | Merged in #1101 as c33fecc7, expanding uv installation docs, documenting setuptools for Sphinx builds, and adding a changelog entry. | |
| #5436 update uv.lock, fix docs | snapcraft | merged | Merged as 146b215b1: refreshed uv.lock to fix h11 CVE GHSA-vqfr-h8mv-ghfj, removed a leftover confdb import, and fixed local docs build errors. | |
| #956 fix: make uv plugin re-entrant on code changes | craft-parts | merged | Merged PR #956 as commit a35ccbfe, making the uv plugin re-entrant so source-code changes are detected without manually cleaning the parts build space. |