Update docs to cover uv managed installations by davisagli · Pull Request #2072 · plone/documentation

davisagli · 2026-03-25T23:20:35Z

Fixes plone/cookieplone-templates#354

Summary:

Update conceptual guide on packaging to cover more of the tools used in the community
Update "Override core Plone packages" how-to to include uv-managed installations, and organize into tabs based on the different package managers.
Update "Install Plone add-ons" how-to to include uv-managed installations, and organize into tabs based on the different package managers.

📚 Documentation preview 📚: https://plone6--2072.org.readthedocs.build/

…verview/index.md

…n tabs

stevepiercy

First pass on draft. I think we'll need another pass or two. Thanks for your work on this!

docs/conceptual-guides/package-management.md

docs/glossary.md

docs/admin-guide/override-core.md

docs/conceptual-guides/package-management.md

Co-authored-by: Steve Piercy <web@stevepiercy.com>

davisagli

@stevepiercy Thanks for the quick first-pass review. I applied most of the suggestions and will follow up later on the others.

docs/admin-guide/override-core.md

docs/conceptual-guides/package-management.md

docs/glossary.md

davisagli · 2026-03-26T03:11:28Z

I've now updated a couple more chapters. I think this is ready for review.

stevepiercy · 2026-03-26T07:04:51Z

@davisaglis how about on every commit to main in cookieplone-templates, run CI to automatically tag it with a timestamp, then use that tag when running Cookieplone?

I just now looked, and it appears that @ericof had a similar thought, based on https://github.com/plone/cookieplone-templates/releases/tag/20260320.1. Should I create a new issue in cookieplone-templates to have this discussion?

- Break steps into subheadings, starting with configure the add-on installation

…sing specificity.

…identical. Combine into the project creation method instead.

…Its target audience is first-timers.

…. Its target audience is first-timers. - Create new subsection for installation of the add-on. - Sync tabs.

… and installation, and sync tabs as that for PyPI installation

stevepiercy

I created a separate PR for docs/admin-guide/add-ons.md only. I haven't reviewed the other files closely yet. I think that a lot of the work in #2073 could be reused here.

docs/admin-guide/add-ons.md

docs/admin-guide/override-core.md

docs/conceptual-guides/package-management.md

davisagli · 2026-03-26T17:29:54Z

@davisaglis how about on every commit to main in cookieplone-templates, run CI to automatically tag it with a timestamp, then use that tag when running Cookieplone? I just now looked, and it appears that @ericof had a similar thought, based on https://github.com/plone/cookieplone-templates/releases/tag/20260320.1. Should I create a new issue in cookieplone-templates to have this discussion?

@stevepiercy I think it's worth discussing if we can improve our release process for cookieplone-templates. But I want to keep that out of scope for this PR, where my goal is to document the status quo better. So yes, a new issue there sounds good.

(Also it doesn't really help here, because the distinction that matters is whether or not the project is configured as uv-managed, and as I realized yesterday, that varies by other factors than just the cookieplone-templates version.)

Build upon #2702

- Update override-core.md to follow the improvements in add-ons.md - Factor out the instructions for restarting the instance into _inc/_build-and-restart.md - Use a simpler check for whether it's a uv-managed Cookieplone project or not

davisagli · 2026-03-26T18:10:58Z

@stevepiercy I tried to update override-core.md to follow your improvements from add-ons.md. I also moved the repeated instructions for restarting the instance into a snippet in the _inc folder.

erral · 2026-03-27T16:34:12Z

I have created a PR for mxdev adding support for the uv.tool.sources option, hopefully we can use that option too in case someone sticks to mxdev for handling checkouts mxstack/mxdev#81

* More uv managed revisions - The instructions for installation from PyPI have only two options, Cookieplone and Buildout, not the three options from the include. The attempt to avoid DRY with an include won't work here. * - DRY for complete the add-on installation * "mxdev" isn't an inline literal * "mxdev" isn't an inline literal * tighten up spacing * grammar * Increasing specificity * Make URL clickable * Add an introductory paragraph to the empty subheading * - Link to sections in add-ons documentation - spelling of mxdev and pip - Oxford comma * Fix Vale errors * Fix Vale errors * Remove unnecessary section subheading * Promote uv as the first package manager, and combine its first two sentences. * MyST markup, grammar, link to the pip interface for uv * Update docs/conceptual-guides/package-management.md * Update docs/admin-guide/override-core.md Co-authored-by: David Glick <david@glicksoftware.com> --------- Co-authored-by: David Glick <david@glicksoftware.com>

stevepiercy · 2026-03-27T23:10:35Z

@erral would you like to create either a suggestion or a separate PR against this branch to document the option, or should we wait until your PR in mxdev gets merged and create a new issue as a placeholder to update these docs?

I'll do a final review of this PR tonight. I think it's good, but I ought to check against the recent merge of the other PR.

stevepiercy

I think this is ready to merge. @davisagli if you agree, would you please do the honors?

stevepiercy · 2026-03-28T03:18:39Z

@erral I created a new issue as a placeholder for whenever your PR gets merged.

#2076

davisagli added 3 commits March 25, 2026 15:40

Be more general about expected familiarity with Python packaging in o…

cb242c3

…verview/index.md

Update conceptual-guides/package-management.md to cover more tools

ee74297

Add uv-based instructions to admin-guide/override-core.md, organize i…

7e9ee20

…n tabs

github-project-automation bot added this to Plone Documentation Mar 25, 2026

github-project-automation bot moved this to New in Plone Documentation Mar 25, 2026

davisagli requested review from ericof, erral, fredvd and stevepiercy March 25, 2026 23:20

davisagli mentioned this pull request Mar 25, 2026

Update docs and track advanced feature we want to bring into a uv managed backend plone/cookieplone-templates#354

Closed

5 tasks

stevepiercy requested changes Mar 26, 2026

View reviewed changes

github-project-automation bot moved this from New to In Progress in Plone Documentation Mar 26, 2026

Apply suggestions from code review

89c347d

Co-authored-by: Steve Piercy <web@stevepiercy.com>

davisagli commented Mar 26, 2026

View reviewed changes

davisagli added 5 commits March 25, 2026 18:56

More updates from review

cd84028

Fix formatting/warnings in glossary

0f5e395

Update conceptual-guides/make-backend-build.md

43d90ef

Update admin-guide/add-ons.md

7bb05f9

Revise after testing

f919508

davisagli marked this pull request as ready for review March 26, 2026 03:11

davisagli changed the title ~~[WIP] Update docs to cover uv managed installations~~ Update docs to cover uv managed installations Mar 26, 2026

stevepiercy added 6 commits March 26, 2026 00:57

Extension of PR #2072

31ac9dc

- Break steps into subheadings, starting with configure the add-on installation

Added guilabel role, and reversed the order of instructions in increa…

f8b392b

…sing specificity.

The instructions for installation from PyPI for both uv and pip were …

a1ac3f9

…identical. Combine into the project creation method instead.

Move tip outside DRY, and combine both the original and new options. …

72c0b9c

…Its target audience is first-timers.

- Move tip outside DRY, and combine both the original and new options…

358fefc

…. Its target audience is first-timers. - Create new subsection for installation of the add-on. - Sync tabs.

- Repeat for source installation the same DRY, split of configuration…

bde905b

… and installation, and sync tabs as that for PyPI installation

stevepiercy reviewed Mar 26, 2026

View reviewed changes

docs/admin-guide/add-ons.md Outdated Show resolved Hide resolved

docs/admin-guide/override-core.md Outdated Show resolved Hide resolved

docs/conceptual-guides/package-management.md Outdated Show resolved Hide resolved

davisagli added 2 commits March 26, 2026 10:39

Merge pull request #2073 from plone/uv-managed-stevepiercy

8ca912c

Build upon #2702

Several updates:

4dd55dd

- Update override-core.md to follow the improvements in add-ons.md - Factor out the instructions for restarting the instance into _inc/_build-and-restart.md - Use a simpler check for whether it's a uv-managed Cookieplone project or not

davisagli requested a review from stevepiercy March 26, 2026 18:11

stevepiercy mentioned this pull request Mar 26, 2026

Automate release tags on each commit to main plone/cookieplone-templates#356

Open

stevepiercy mentioned this pull request Mar 27, 2026

Another revision of uv-managed branch #2074

Merged

Link to Python standard library

16cd84f

stevepiercy approved these changes Mar 28, 2026

View reviewed changes

stevepiercy mentioned this pull request Mar 28, 2026

Update mxdev managed installations with uv.tool.sources #2076

Open

davisagli merged commit 178f754 into 6.0 Mar 28, 2026
3 checks passed

davisagli deleted the uv-managed branch March 28, 2026 15:39

github-project-automation bot moved this from In Progress to Done in Plone Documentation Mar 28, 2026

Uh oh!

Conversation

davisagli commented Mar 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

stevepiercy left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

davisagli left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

davisagli commented Mar 26, 2026

Uh oh!

stevepiercy commented Mar 26, 2026

Uh oh!

stevepiercy left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

davisagli commented Mar 26, 2026

Uh oh!

davisagli commented Mar 26, 2026

Uh oh!

erral commented Mar 27, 2026

Uh oh!

stevepiercy commented Mar 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

stevepiercy left a comment

Choose a reason for hiding this comment

Uh oh!

stevepiercy commented Mar 28, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

davisagli commented Mar 25, 2026 •

edited

Loading

stevepiercy commented Mar 27, 2026 •

edited

Loading