docs: clarify how to use the uv plugin
Metadata
Current evaluation
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.
Suggested action: —
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 |
|---|---|---|---|---|
| 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. | |
| qwen3.6-35b-a3b-mtp-q6 | — | — | Merged documentation updates clarifying uv plugin usage. Added astral-uv snap to examples, specified dependency placement in pyproject.toml, and emphasized uv.lock requirements. Resolves #2238. |
Update history
No update history recorded yet.
Related issues
| Issue | Project | State | Summary | Similarity |
|---|---|---|---|---|
| #1101 Improve uv plugin doc | craft-parts | merged | Merged documentation updates for the uv plugin, expanding installation instructions, adding a setuptools dependency, and including a changelog entry. A CLA check failure was identified and resolved via a separate CI workflow update. | |
| #960 docs: add uv to list of plugin options and to dependency explanation | rockcraft | open | One-line docs change adding uv to the plugin options list and dependency explanation. Approved by 2 reviewers, but 2 unresolved review comments remain and the snap-tests CI job is failing. No activity for ~11 months. | |
| #1589 docs(uv): clarify stage-packages usage | craft-parts | merged | Merged documentation update clarifying uv plugin virtual environment placement and stage-packages usage. Resolves #1580. Approved by two reviewers and force-merged after one OSV security scan check failed. | |
| #1486 docs: update uv plugin reference | craft-parts | merged | Merged after approval. The PR updates the reference documentation by adding details for UV_COMPILE_BYTECODE and applying minor fixes to other sections. CI checks passed and changes were integrated. | |
| #2156 docs(how-to): add how-to migrate to uv | charmcraft | merged | Merged documentation update adding a how-to guide for migrating to the uv plugin, based on the poetry plugin page. Includes a typo fix and approved cross-reference link to the uv plugin reference. | |
| #1086 fix: validate uv plugin for newer uv versions | craft-parts | merged | Merged fix for uv plugin validation in versions 0.7.0+. Replaced uv version with uv --version to prevent conflicts with project pyproject.toml parsing, resolving build failures in newer uv environments. |