Update docs and track advanced feature we want to bring into a uv managed backend

[fredvd]

This is a follow up from PR #350 that was merged, but we need to update the docs for this and keep track of some advanced features that would be great to have documented and/or added to the cookieplone templates.

We would need to do some research a few of those further, but ideas and options are already in the (closed) PR discussion.

• Override use a different version of a released package than the KGS managed by uv in the pyproject.toml I don't fully understand yet why this should be done with an 'extra' list in pyproject.toml and changes in repoplone. yet. Once the project template is generated you update /backend/pyproject.toml is my impression.

• Then we want to support source checkouts: this works by using uv.tool.sources in the pyproject.toml, but the checkout itself to the filesystem is not done by uv (it is done by mxdev). AFAICS what @erral suggested in the PR is to lext mxdev do this part stll. But @ericof mentioned repoplone could take care of this as well. How much I have used and like the mxdev features, keeping only this part in mxdev for doing checkouts and it can work, is a guarantee to confuse people using the generated project scaffold.

@davisagli posted a list of where mxdev is mentioned. on the PR Some questions:

• Can we 'migrate' the features in short enough time that we can update the documentation in one go? Or will this take to olong and should we do the update in two phases? How long do we give ourselves for that (timeboxing a bit).

• @stevepiercy Should we copy the resulting "pages to update with what" into one or two plone/documentation issues?

@ericof Created a separate documentation issue on plone/cookieplone#132, but this is about the improved cookieplone 2.0 functionality AFAICS and about the template tooling, not wisdom/FAQ's about using the tools in the generated scaffold to develop/run/release your project.

Meta "how to make future efforts easier: we have been discussing this before, with updates to the frontend/backend tooling in a generated plone project scaffold, spreading the basics and advanced features over 5-10 pages in the documentation is not much 'fun' to track and update.

We already did a great job to let trainings refer to docs.plone.org, but we should check those as well. But also inside docs.plone.org, the fewer pages we have on the details and we refer to , the easier future updates will be.

But just as there is 'philosophy' about cookieplone, there is also extra tips/tricks/lore around the generated cookieplone scaffold and how to use it.

This is an explorartory and 'what should we do issu" so we are aware and can update each other of the scope and attempt for a logical 'order'. What am I missing, or what are better alternatives?

To do

The following docs should be reviewed and updated:

• https://6.docs.plone.org/overview/index.html
• https://6.docs.plone.org/conceptual-guides/package-management.html
• https://6.docs.plone.org/admin-guide/override-core.html
• https://6.docs.plone.org/conceptual-guides/make-backend-build.html
• https://6.docs.plone.org/admin-guide/add-ons.html

[stevepiercy]

I'd suggest adding closing criteria. That means either create a nice todo list of checkboxes in the description, create sub-issues in the description, or both.

@davisagli put together a list of files to update in plone/documentation whenever uv replaces mxdev in #352 (comment), which was merged, but I don't know whether that PR is now effective or released. Currently there's no issue in documentation to track those changes.

[erral]

What worries me is the really fast pace of a basic tool like this for scaffolding Plone projects. I know that the technology flies, and in this AI era it flies even faster, but in 1 year time we had 3 versions of cookieplone-templates doing things in a slightly different manner, that may look like complete changes for an "outsider" or a "just user" person.

I really appreciate all the work here, but one has to be on top of the development to follow and understand what happens and how it evolves.

So, now we have ditched mxdev and mx.ini from the project template, we have to update the docs ASAP, as fast as we have merged those changes, otherwise it may look half-baked for anyone reading the docs.

[stevepiercy]

now we have ditched mxdev and mx.ini from the project template

Was this released, and now being used as the default?

If so, we could do much better in the future. A PR in plone/documentation with changes could be made in parallel to proposed changes to the templates, and both PRs merged simultaneously.

[ericof]

I agree with the criticism and will refrain from making any further improvements here.

Sorry for the inconvenience.

[stevepiercy]

@ericof I think the development pace is good.

I think the communication about the development changes to the end user is missing. That can be improved.

I still don't know whether something was released, is now being used, but not yet documented in plone/documentation, or is in a pre-release state and needs developers to test it.

For something as common and important as creating a Plone project, we should shout it from the mountain tops and praise it. Social media, website, Community Forum, email newsletter, the works. When people complain, we can then say, "Well, we did X, Y, and Z to communicate the change. What else could we do to let you know about the change?"

[davisagli]

I added a todo list to this issue (it may not be complete) and started working on the updates in plone/documentation#2072