integrate coredev.buildout (was PR #1670)

[stevepiercy]

Preview of pull request

https://plone6--1671.org.readthedocs.build/contributing/core/index.html

Description

This time without submodules

ToDo before merge

• @jensens insert a Mermaid diagram in docs at https://github.com/plone/documentation/pull/1671/files#diff-36199f263c1ec44ec26fc136ea22e39344bf44acc065e03e0fe26bc263d2f9f2. See Insert a Mermaid diagram in conceptual-guides/package-dependencies.md #1683
• Purge the files at the root in coredev.

ToDo after merge

• @plone/framework-team update links in to correct location https://plone.org/community/teams/framework
• Fix link in PLIP template http://docs.plone.org/develop/coredev/docs/plips.html to point to new docs.
  • Volto see Update the link to the new PLIP page volto#6176
  • Products.CMFPlone See Update the link to the new PLIP page Products.CMFPlone#3988
  • Other?

Closes

• Closes PLIP template has a legacy 5 URL #1495
• Closes Migrate buildout.coredev docs into Plone 6 Documentation #1486
• Closes buildout.coredev docs need to be pulled into Plone 6 Documentation buildout.coredev#840
• Closes Contributing to Products.CMFPlone is broken Products.CMFPlone#3973

References

• Edit Contributing docs #1278

[stevepiercy]

I could really use a review from anyone who cares about how to contribute to and develop in Plone core of just this one file (https://plone6--1671.org.readthedocs.build/contributing/core/index.html) in this commit: e2fb4f8 @jensens @petschki @ericof @MrTango @sneridagh @davisagli @thet This one file is the key to getting new suckers contributors to Plone core.

For anyone who cares about releasing Plone, specifically @mauritsvanrees, I especially would like a review on https://plone6--1671.org.readthedocs.build/contributing/core/release.html

More to come, but these two pages are super critical to the others.

[petschki]

When it comes to "Edit packages" I always create a local.cfg ( -> ignored in .gitignores ) which looks like this:

[buildout]
extend = 
    core.cfg

auto-checkout +=
    plone.app.event
    icalendar
    my.package

[sources]
# add sources here, which arent in the sources.cfg already or need another branch
my.package = git git@github.com:collective/my.package.git branch=main

and then run

$ ./bootstrap.sh -c local.cfg

so you do not have to edit any of the original files ( which might also get manipulated by mr.roboto ... eg. checkouts.cfg )

[stevepiercy]

so you do not have to edit any of the original files ( which might also get manipulated by mr.roboto ... eg. checkouts.cfg )

@thet also suggested something similar.

buildout.local.cfg

[buildout]
extends =
  buildout.cfg

auto-checkout =
    # Add packages which you want to develop
    plone.app.caching
    plone.caching
    plone.app.event
    icalendar
    # others
    ...

However further on, according to this ancient documentation, the release manager would look in checkouts.cfg to see what needs to be released. Additionally Jenkins looks at this file—and not any custom file—to run the full test suite. Is all that correct?

It would be good to verify what is the actual preferred process to contribute to Plone core.

the changes I requested were done but I didn't have time to review the other parts of the PR yet

[stevepiercy]

@davisagli I would like to merge this after the Volto Team meeting on Tuesday, July 2. Will that work for you?

[jensens]

Sorry for the delay, I'll look into it ASAP.

[gforcada]

This whole page is outdated, it does not mention mr.roboto, GHA nor plone/meta which make almost all the rules described outdated.

Sorry that it took me forever to react on the call to help on this PR 🙇🏾

I can do the update, should I push it directly to this branch? 🤔

[stevepiercy]

@gforcada please create a PR against this branch for review. Do not push commits directly to this branch.

I'm not clear on which repositories plone/meta applies. From what I know, many repositories use make and not tox, including Volto, plone.restapi, and Documentation. Until there is both agreement and implementation for a unified approach, I don't know whether plone/meta should be declared as authoritative for all projects under the Plone GitHub organization.

[gforcada]

Ok, thanks I will do that (the branch).

As for plone/meta or make, well, it's literally all but volto related packages that already use plone/meta. There are a few that are missing (like CMFPlone) that I did not had the time to apply plone/meta to it.

But this documentation is meant for classic UI, or? 🤔 I meant I saw quite a few references that always branch to say "if you are doing volto then see ../volto"

[stevepiercy]

This part of the documentation is intended for anything that is not Volto, which includes Classic UI, core add-ons, and other core packages.

There is also an effort with cookiecutter and mxdev, which is intended to replace buildout, at which point another rewrite of docs will need to take place.

I don't know how that reconciles with plone/meta. I just document what I understand.

[gforcada]

plone/meta and mxdev/cookiecutter are orthogonal, at least I'm 100% sure with mxdev, with cookiecutter that depends on what's being done, of for which purpose is used 😓

I've seen so many cookieXX repositories, that I'm no longer sure what one should use 🤷🏾

but if the goal is to replace zc.buildout, then plone/meta has nothing to do with that and should be fine to document.

Actually plone/meta has quite some exhaustive documentation on its own 😄

[stevepiercy]

@gforcada even before your review and subsequent pull request, I had a lot of issues with this document. It never had a high-level review. I apologize for not bringing up my concerns earlier, but here they are now.

1. It's not clear what is the purpose of this document.
2. It's not clear who is the target audience.
3. Is it a tutorial, a how-to guide, an explanation, or a reference? See https://diataxis.fr/ for details of what these categories mean.
4. Much of the content is redundant to existing parts of the documentation, as well as within this pull request, including:
   • https://6.docs.plone.org/contributing/first-time.html#set-up-your-environment
   • https://6.docs.plone.org/contributing/index.html
   • https://github.com/plone/documentation/pull/1671/files#diff-92572efaca37b0041952183745916a031065e6fc8f04a0a5faa26ad023dc609f

Once we have an idea of what we want to do, then we can rewrite this document to achieve that goal. I'd be happy to have a chat with you in real-time in Discord, or continue the conversation here.

---

For cookie*, the primary repo is https://github.com/plone/cookieplone. It uses templates found in https://github.com/plone/cookieplone-templates. I don't know whether that repo uses plone/meta itself, but its templates do.

cookie* uses mxdev, as described in https://6.docs.plone.org/install/manage-add-ons-packages.html#manage-plone-backend-packages-with-mxdev.

---

Are these files plone/meta's documentation?

• https://github.com/plone/meta/blob/main/README.md
• https://github.com/plone/meta/blob/main/config/README.md

[gforcada]

In reverse order 🙃

• yes, that's the documentation for plone/meta

• oh nice, thanks for the cookie pointers, now it's a bit more clear to me, the (not to be answered and solved now) is how that works with mr.bob and bobtemplates.plone and all that ecosystem, or again, we have cookie* for volto and mr.bob for classic UI? 🤔

• for this document, I would say that it's an explanation of how the CI system works, being the target audience newcomers.

With the links you provided (thanks!) I would say it could be linked from https://6.docs.plone.org/contributing/index.html#continuous-integration, then, we could simplify my PR to remove the explanation about PRs and be more focused only on the tooling involved.

How that sounds?

As for talking in discord, sure, this week, I do have time in European evenings, something like https://www.timeanddate.com/worldclock/converter.html?iso=20240708T170000&p1=37&p2=202 ?

[stevepiercy]

• OK on meta docs.

• I encourage you to try cookieplone for fun. If there is something missing, or is not clear how to do, then file an issue.

• I think an explanation page would be good. I do not know all the parts of CI, what each part does, or how they al work together to fulfill specified tasks.

  In that context, let's change the document title to "Continuous integration". If we keep "essential" or "practices", then we start telling the reader how to do things or what things they should do, which makes it a how-to guide, not an explanation.

  Also if you use Mermaid for diagrams, you could even draw a picture of the workflow.

[stevepiercy]

@gforcada to get this PR merged, I will remove the CI stuff entirely. It's not correct and should not be published in its current state. The rest of it is good. We can add the CI stuff in another PR.

I'll work on pulling it out of this PR, and moving it back to the coredev directory to preserve the grammar and MyST work I did. I'll do that sometime this week.

[tisto]

LGTM!

[stevepiercy]

Thanks everyone! Merging!

@gforcada let's work on the CI page when you get the chance.

[mauritsvanrees]

Thanks for pushing this, Steve!