volto Add docs for upgrading Volto in a Cookieplone project

[x] I signed and returned the Plone Contributor Agreement, and received and accepted an invitation to join a team in the Plone GitHub organization.
[x] I verified there aren't other open pull requests for the same change.
[x] I followed the guidelines in Contributing to Volto.
[x] I succesfully ran code linting checks on my changes locally.
[x] I succesfully ran unit tests on my changes locally.
[X] I succesfully ran acceptance tests on my changes locally.
[x] If needed, I added new tests for my changes.
[x] If needed, I added documentation for my changes, either in the Storybook or narrative documentation.
[x] I included a change log entry in my commits.

Closes #7074

📚 Documentation preview 📚: https://volto--7121.org.readthedocs.build/

May 27 '25 09:05 silviubogan

@sneridagh do we want to support this method, given we tell developers to follow the only currently supported method as described in https://6.docs.plone.org/volto/upgrade-guide/index.html?

I really don't think we should have yet another supported method to install stuff, as we all know how that turned out with the Plone Unified Installer, Plone in a Box, Vagrant, and other abandoned methods.

May 27 '25 10:05 stevepiercy

I would definitely remove running git pull in the core folder from the docs, it is not valid as core folder is managed by mrs.developer.json.

So the recommendation should be updating the version in .mrs.developer.json and running make install.

May 27 '25 12:05 erral

@erral

I would definitely remove running git pull in the core folder from the docs, it is not valid as core folder is managed by mrs.developer.json.

I agree it is bad, but for the short term it can be useful (temporarily). I've specified in the docs at the top of the new section the recommended solution.

As I've said in https://github.com/plone/volto/issues/7074, make install does not always update the fetched main branch if, before, it was the same main branch but another commit.

It is as I said in the changed file:

and remove the key tag and run make install but it will be only a one-time fetch of the main branch, because of mrs-developer not supporting refetching the same branch for different tips during time, in some occasions.

May 27 '25 14:05 silviubogan

@erral Tomorrow I will try to replace the command make install with something that works well.

May 27 '25 17:05 silviubogan

@silviubogan did you see my comment yesterday in the other issue, right? We are not encouraging that people use the core checkout in this way. I think I left it clear in https://github.com/plone/volto/issues/7074#issuecomment-2911372460.

There's nothing to fix here.

May 28 '25 07:05 sneridagh

@sneridagh @erral @stevepiercy I've made another commit. Please review it. I still believe there is something useful for beginner contributors in it.

May 28 '25 08:05 silviubogan

There's nothing to fix here.

@sneridagh but there is. We need to explicitly add the statement "Don't upgrade Plone's core code base in a Cookieplone project. Instead see how to upgrade the core code base (URL TBD) in a Cookieplone project."

Unfortunately we lack universal documentation, although we have this for Volto https://6.docs.plone.org/volto/upgrade-guide/index.html#upgrade-18-cookieplone-label. We also have to contend with the Plone Upgrade Guide. Let's chat to figure out what is needed and where it should go.

@silviubogan I'm sorry, but as I previously stated in https://github.com/plone/volto/pull/7121#issuecomment-2912059804 and https://github.com/plone/volto/issues/7074#issuecomment-2878134898, I doubted whether this method is or should be supported, and @sneridagh has now confirmed it twice.

I don't know why you ignore these statements. This PR shall not be merged using an unsupported method. Please don't invest any more time on it.

May 28 '25 08:05 stevepiercy

Unfortunately we lack universal documentation, although we have this for Volto https://6.docs.plone.org/volto/upgrade-guide/index.html#upgrade-18-cookieplone-label. We also have to contend with the Plone Upgrade Guide. Let's chat to figure out what is needed and where it should go.

You are correct, let's complete and untangle this particular case. Let's talk about it when we have a moment.

May 28 '25 12:05 sneridagh

@fredvd Are you preparing documentation about this, right? Do you plan to add it to the Plone docs?

Jun 22 '25 15:06 sneridagh

@fredvd I chatted with @sneridagh yesterday during the sprint. Here's what we discussed, plus a couple more things. Would you both please look this over?

[ ] Rename Plone Upgrade Guide to "Plone backend upgrade guide". This will also update the label in Upgrade Plone.
[ ] Add text in Upgrade Plone to better explain what are the components and better guide readers to what they want to upgrade.
[ ] In Upgrade Plone, under the most relevant guides, add the most recent anchor to upgrade to Volto 18, the latest stable version.
[ ] Create an include from the content at https://6.docs.plone.org/volto/contributing/version-policy.html#plone-python-and-plone-rest-api-compatibility and include it in Upgrade Plone.

Aside from this list, @fredvd if you have just notes of step-by-step things to do and can pass that along to me, I can write up the documentation for it and place it in the appropriate location. Specifically we need to handle:

Upgrade your Cookieplone-generated project Plone core
Migrate your Cookieplone-generated project to a newer version of Cookieplone

Please let me know. Thank you!

Jun 25 '25 08:06 stevepiercy