Create Plone Core Code contributing documentation

[stevepiercy]

• Demote documentation contributing into its own folder
• Create First-time contributors documentation

Refs: #1278

This is a huge change from v5. I want to make sure that the universal content is correct, especially with all the newbies coming in to Plone via Volto.

I will have another PR to update Volto docs after this is merged.

[netlify]

✅ Deploy Preview for 6-docs-plone-org ready!

Name	Link
🔨 Latest commit	e7a1520
🔍 Latest deploy log	https://app.netlify.com/sites/6-docs-plone-org/deploys/6430774b5b40c90008a6fb2e
😎 Deploy Preview	https://deploy-preview-1478--6-docs-plone-org.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site settings.

[stevepiercy]

Thank you for your review @jensens!

I'd like one more review from either @tiberiuichim @mauritsvanrees @fredvd @sneridagh @ksuess or anyone else. If not, I'll merge after 7 days since opening on Apr 8 or thereabouts.

[fredvd]

Looking Good! That's a major clean up. Things are missing now, but we can add them (with careful selection) to this frame.

---

These are not remarks specifically about the current docs in detail, @stevepiercy you did an excellent job by trying to condense 5-8 sources into something coherent on which we can build and fill in the details. This is all about confusing things that have been going on for the last 2-3 years and are part of the old cruft.

---

I would suggest to remove the word 'core' from the contributing documentation (and in general). We have been using 'core' for years with the meaning of a 'core developer' being someone who can contribute to the 'Plone core' distribution, but we have now at least 5 area's/domains that are kind of separate when looking at knowledge and expertise needed. Plone backend/ClassicUI, Volto, Documentation, Training and 'Sites'. I would just call us 'Plone contributors'.

I think it's also a Python sub culture thing (Python Core developer). Core likely only confuses new people coming into the community and makes it sound elitist. 'Core distribution' is also confusing at the moment, because is that plone-backend without plone-frontend now that Volto is software/runtime wise a separate process/service, but in marketing terms the default frontend of "Plone 6".

We might get back a 'core' in 2-3 years, where core will be the content api/backend server component. And ClassicUI and Volto will be 2 code separated frontends for that core. But we're not there yet by far.

The main section could be called "Contributing to Plone" then.

---

Like @jensens suggests, I wouldn't list packages under Plone (core) packages at the start of the contributing section. The existing but different/specialised contribution guidelines for these packages exists for a historical reason: they were started as add'on packages and later added to the base distribution. That is valid for plone.app.event, plone.app.contenttypes (first as DX default contenttype for Plone 4, jay), plone.app.multilingual, plone.api, plone.app.contentlisting. They aren't projects off their own anymore. plone.restapi as well, while it was still in development it moved much faster to expose and provide needed endpoints to Volto, but that's I think much less the case nowadays.

There is some good advice in those specific contirbution pages, like naming conventions for plone.restapi, but we can add them to a separate section: extra guidelines for specific packages.

Like described above: I'd describe the 4 area's where People can contribute: Plone 6 base / Classic UI, Volto, Documentation

What I'm struggling with if these should be included here as well, are contributions to our operations: the code for the websites plone.org, ploneconf.org, our AI-team repo's, the jenkins/CI setup, our installers/image building repo's. I assume for these we also want to have a signed contributor agreement to not run into any legal issues later. But I'm not sure if this has been thought about before.

---

First Time Contributors (FTC)

• FTC's are no longer able to edit other peoples issues or comments AFAIK, so that remark can be removed (Developers do get that persmissions)

• I'm conflicted about the 'never ask to be assigned to an issue. The effect is that people start contributing /working on issues without communicating with other devs first if they understand the issue and if their proposed solution is realistic, achievable and not over-engineered. We shouldn't pretend that our GitHub issues are filled with are 100% clear and actionable tasks to contribute.

Maybe we should reword that, because under Work with Github issues (2) is written what you should do: first discuss and find consensus on the issue with other devs, then an assignment could follow from that discussion

---

IMHO (6.)docs.plone.org should contain all documentation on developing for Plone and its developer documentation, and be self contained. What I saw last week is that there was some duplication with details on what is exactly in the contributor agreement and why (https://plone.org/foundation/contributors-agreement). I would suggest having a single source of truth and move all developer related info into these (developer docs). This should also be the start of having a more clear separation of plone.org and docs.plone.org plone.org is marketing/communication/community .

There is also some scary stuff in that document above about relicensing Plone to commercial parties. I know that was a thing in the first 3-6 years of Plone's existens, but after 1-2 weird adventures I don't think that's something that the foundation would strive for or allow in 2023 (and extremely unlikely to happen and has been the death of many open source projects) . @jensens , can you ask at a future Board meeting if this is still relevant? Reading this in 2023 gives me the jitters honestly.

---

[fredvd]

Oh, one thing I wanted to add but forgot with the first time contributors A large part of the GSOC manageability problems started because we suggested to students interested in applying for a proposal is that they should become active in the Plone community first.

It kind of gave them the impression that contributing was a requirement, and if it wasn't then it would still increase their a more favorable judgemen of their proposal. I would suggest to rewrite the section under Plone contributors team, specfically "New users, including GSoC applicants, are assigned to the" .

Officially a GSOC applicant should only be sending in a signed Contributor Agremeent after the applicant proposal was selected by the mentors and he/she/they is accepted into GSOC. We need to do a lot of negative selling next year if we are selected back into GSOC as an organisation. "Why do you want to contribute to Plone? " Don't, unless..... ;-)

[jensens]

short commenting @fredvd good long write ;)

• ad sections 3: full ack
• ad section 4: full ack. also no idea how to tackle infrastructure, but +1 for contributor agreement needed.
• ad section 5: assigning will not work. but maybe dropping a comment "I am working on this, here is my branch" would be a way?
• ad section 6: complex, right. I like the idea of getting all together in one place and clean up our evolutionary grown mess. But it is lots of work.

[stevepiercy]

I made a few more revisions, per feedback from @jensens and @fredvd. Please take another pass, and let me know.

1. Removed "core" and "code" as appropriate.
2. Reworded the list of packages and removed obscure ones, keeping the most actively developed ones. IMO index.md must be an entry point for specific contributing guidelines, in other words a collection of links to the necessary details for how to contribute to each specific package, but not the details themselves. Where else should it go, if not the index?
3. Classic UI has no entry point for contributors AFAIK. If you know of one, I would include it.
4. FTC's flooded Volto with "please sir assign me this issue" comments, so I am pretty adamant about keeping that statement as it is for its clarity. Additionally, members of privileged teams don't want to respond to a flood of requests, don't want to manage assignment of FTCs, and these comments just add clutter the issue and obscure relevant discussion. I estimate I hid or deleted about 100 such comments over the last month. With that said, I added a sentence for what to do instead to explain. I understand this may conflict with subsequently requesting to be assigned to an issue after a discussion, but the vast majority of the FTCs do not bother to read details.

As far as GSoC messaging, we should have discussed with @ebrehault and whoever else was coordinating things. I was new to GSoC as a mentor, and too busy at the time to take note of issues. Here are my suggestions.

• Add an instruction to read and follow the GSoC Contributor Guide's Writing a proposal.
• Remove all things that are optional.
• Remove the Note.
• Remove "Introduce yourself to our community".
• Point to current documentation and contributing, instead of Plone 5 versions.
• Remove duplicate mention of asking questions.
• Direct them to use only the Community Forum and the GSoC app to communicate. No private messages, emails, @-ing on GitHub, Discord chat. Doing so will hurt your chances of being accepted because you would demonstrate an unwillingness to follow instructions.

[fredvd]

Looks good !

There's one wording issue I see, but I can't come up with a better name for packages. So maybe indeed using Products.CMFPlone solves the problem and we can document there the parts from coredev that are specific for the backend for now.

[stevepiercy]

There's one wording issue I see, but I can't come up with a better name for packages.

Ah, now I see what you were driving at. s/package/project. A package is a project. Documentation, Docker containers, and demos are projects, but not packages. I think that covers it.

[stevepiercy]

sigh poor web.archive.org is timing out for linkcheckbroken again. We should consider whether to grab the content and incorporate it in the docs or purge the links (especially if permission is not granted) if this persists.

[fredvd]

Yes! Projects, so obvious. Thanks! I should log off ;-)

[davisagli]

This is a fantastic improvement. Thanks @stevepiercy @fredvd @jensens!