Skip to content

Commit 278a3fb

Browse files
ksuessksuess
committed
Merge branch "backend-6" into branch "6-dev"
1 parent df9db21 commit 278a3fb

File tree

3 files changed

+271
-0
lines changed

3 files changed

+271
-0
lines changed

‎docs/backend/README-doc-writers.txt‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
Training vs Reference
2+
---------------------
3+
4+
The Mastering Plone training contains a lot of explanation and is
5+
a 'story telling' version of the reference documentation we have here.
6+
It has been well maintained and also has been updated to have chapters
7+
on the new React Frontend. Because of the purpose (training) It might
8+
however not have the right order for the happy path and much more
9+
verbose than the level we want to achieve here. But please take a look
10+
at the explanation there if you work on documentation a task here.
11+
12+
13+
14+
Scaffolding
15+
-----------
16+
17+
There has been some discussing about bootstrapping during the 2021
18+
PloneConf at the fanzone. The reference documentation should contain
19+
the first steps to generate a working Zope/Plone app server
20+
configuration that requires scaffolding. The current scaffolding tool
21+
that has been well supported updated and used in the community is
22+
plonecli. This tool internally depends on bobtemplates, but we
23+
shouldn't mention that (implementation detail).
24+
25+
To avoid having a too strict dependency on plonecli but also not
26+
having to write out/document every single file I propose we use/
27+
describe plonecli, but after running discuss/document the files
28+
created and why they are there.
29+
30+
31+
Possible setup for first chapters
32+
---------------------------------
33+
34+
This is only a suggestion/inspiration based on discussions with
35+
Volto frontender on what they first have to create (task oriented)
36+
or modify on the backend when they work on Volto sites. These
37+
could map to chapters
38+
39+
----
40+
41+
* scaffold plone server setup/buildout with add-on directory
42+
43+
* scaffold a content type
44+
45+
(use plonecli in below example for scaffolding, then explain directory structure/files? )
46+
47+
* contenttype: create xml schema or jkcreate the interface zope.schema for the fields
48+
49+
* Create the Item/Container python class
50+
51+
* register the content type in the types xml
52+
53+
* generic setup upgrade step
54+
55+
* upgrade step definition in ZCML to register the generic upgrade step
56+

‎docs/backend/README.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Plone 6 Backend Docs
2+
3+
- All documentation should be written in Markdown.
4+
- If possible, please structure into dirs, this will make it easier to build a structure later.
5+
6+
See the following example
7+
8+
```markdown
9+
/docs
10+
➜ tree
11+
.
12+
├── deploy.md
13+
├── index.md
14+
└── install.md
15+
```
16+
Use a file called `index.md` for creating a index (if needed)
17+
18+
```shell
19+
➜ cat index.md
20+
install.md
21+
deploy.md
22+
```
23+
24+
Thank you!!
25+

‎docs/backend/upgrading/version_specific_migration/v60.md‎

Lines changed: 190 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,190 @@
1+
# Upgrade to Plone 6.0
2+
3+
Plone 6.0 has seen the following major changes.
4+
Some may require changes in your setup.
5+
6+
## Removed portal_quickinstaller
7+
Plone no longer ships with the `portal_quickinstaller` tool (`CMFQuickInstallerTool`).
8+
In existing sites, the standard upgrade will remove the tool.
9+
This is the final step in a deprecation path that started in Plone 5.1.
10+
Documentation on how to switch to GenericSetup and the new installer, can be seen in the old [Plone 5.1 upgrade guide](
11+
https://docs.plone.org/develop/addons/upgrade_to_51.html#installation-code).
12+
13+
See [PLIP 1775](https://github.com/plone/Products.CMFPlone/issues/1775).
14+
15+
16+
## Dexterity site root
17+
For content types, in Plone 4 and 5 you had the option to use the old Archetypes or the new Dexterity framework.
18+
The Plone Site root object was neither: it was in its own class.
19+
In Plone 6, the site root itself is a Dexterity object.
20+
21+
When you upgrade a site from Plone 5.2 to 6.0, at first you will see an empty site root.
22+
Do not panic.
23+
Your contents are only temporarily invisible.
24+
Simply perform the standard migration via the `@@plone-upgrade` view and your content will be visible again.
25+
26+
See [PLIP 2454](https://github.com/plone/Products.CMFPlone/issues/2454).
27+
28+
29+
## Volto
30+
Plone 6 ships with a new NodeJS frontend: Volto.
31+
When you use the `Plone` package in your project, you will get the `plone.volto` integration package.
32+
This package prepares your Plone Site as a REST API.
33+
34+
Note: the classic integrated frontend is still available if you are not ready for the new separate frontend.
35+
Do not use the `plone.volto` package then.
36+
37+
See [PLIP 2703](https://github.com/plone/Products.CMFPlone/issues/2703).
38+
39+
40+
## Archetypes
41+
The deprecated Archetypes contenttypes framework is no longer supported.
42+
Add-ons that define a contenttype, must use Dexterity instead.
43+
44+
See [PLIP 2775](https://github.com/plone/Products.CMFPlone/issues/2775).
45+
46+
47+
## No more temp_folder / tempstorage
48+
49+
The `temp_folder` object in the Zope root is no longer created by default.
50+
If the object is there, but it is broken, the standard Plone upgrade procedure will remove it.
51+
52+
For now, you must explicitly disable the temp_folder if you use buildout:
53+
54+
```
55+
[instance]
56+
recipe = plone.recipe.zope2instance
57+
zodb-temporary-storage = off
58+
```
59+
60+
See [issue 2957](https://github.com/plone/Products.CMFPlone/issues/2957).
61+
62+
63+
## Changed Templates to Bootstrap 5 Markup
64+
65+
All templates in core Plone have been updated to Bootstrap 5 markup.
66+
Add-on authors are encouraged to do the same.
67+
If you have customized a core template, you should check if your change is still needed, and update it to fit the new markup.
68+
Any CSS and JavaScript that relies on a specific structure, or certain ids or classes, should be checked as well.
69+
70+
See [PLIP 2967](https://github.com/plone/Products.CMFPlone/issues/2967).
71+
72+
73+
## Zope 5
74+
75+
Plone 6.0 means we move from Zope 4 to 5.
76+
This drops support for Python 2.7, drops ZServer, and removes deprecated code.
77+
See [Zope 5.0a1](https://zope.readthedocs.io/en/latest/changes.html#a1-2020-02-28).
78+
79+
Some imports may need to change.
80+
Add-on authors should check on Plone 5.2 if their code runs without any deprecation warnings from Zope 4.
81+
If no warnings are shown, the add-on should run fine on Zope 5.
82+
83+
See [PLIP 3058](https://github.com/plone/Products.CMFPlone/issues/3058).
84+
85+
86+
## Modernize Plone default theme (Barceloneta LTS)
87+
88+
The standard theme in Classic UI was updated to Bootstrap 5, CSS variables, and an icon library.
89+
If you have a theme that builds on Barceloneta, you most likely need various changes.
90+
91+
It may be best to start with a fresh theme, and try to keep the changes minimal.
92+
The training documentation lists [three possible theming strategies](https://training.plone.org/5/theming/index.html):
93+
94+
- Create a theme based on Barceloneta
95+
- Create a theme from scratch
96+
- Create a theme based on Diazo
97+
98+
See [PLIP 3061](https://github.com/plone/Products.CMFPlone/issues/3061).
99+
100+
101+
## Python
102+
103+
You may need to use a newer Python version.
104+
Supported Python versions are: 3.7, 3.8 and 3.9.
105+
We recommend the most recent version.
106+
See https://www.python.org/downloads/ for which Python version is still supported by the Python community.
107+
108+
See [PLIP 3229](https://github.com/plone/Products.CMFPlone/issues/3229).
109+
110+
111+
## `plone.api.relation`
112+
113+
The `plone.api` package now has a `relation` module. Add-on authors may want to use this to get, create or delete relations.
114+
115+
See [PLIP 3137](https://github.com/plone/Products.CMFPlone/issues/3137).
116+
117+
118+
## Mockup and resource registry redone
119+
120+
Mockup contains the source of most Classic Plone JavaScript.
121+
The compiled version is in `plone.staticresources`.
122+
123+
Mockup is now based on Patternslib 4.
124+
It uses ES6 module imports instead of RequireJS.
125+
Add-ons for Classic Plone that use JavaScript should be updated to use ES6 modules as well.
126+
127+
The resource registries and their control panel have been simplified.
128+
Add-ons for Classic Plone only need to register bundles, not individual resources.
129+
130+
See [PLIP 3211](https://github.com/plone/Products.CMFPlone/issues/3211).
131+
132+
133+
## Relations control panel
134+
135+
Plone 6 has a new control panel for relations: `@@inspect-relations`.
136+
As Manager you may want to use this control panel to look for and fix possible problems.
137+
138+
See [PLIP 3232](https://github.com/plone/Products.CMFPlone/issues/3232).
139+
140+
141+
## Deprecated unicode property types
142+
143+
Zope 5 has deprecated the unicode property types: ustring, ulines, utext, utokens.
144+
If you use these in your add-on, you should switch to their standard variants: string, lines, text, tokens.
145+
These behave exactly the same on Python 3.
146+
Plone has an upgrade step that goes through all objects in the site, replacing the deprecated properties with the default ones, so you should not see them anymore.
147+
But in your own code you should avoid adding them again.
148+
149+
See [issue 3305](https://github.com/plone/Products.CMFPlone/issues/3305).
150+
151+
152+
## autoinclude
153+
154+
We have replaced `z3c.autoinclude` with `plone.autoinclude`.
155+
Both are used by add-ons (Python packages) to signal with an entry point that Plone must load the zcml of the add-on.
156+
In most cases, the existing entry point can stay the same, for example in `setup.py`:
157+
158+
```
159+
entry_points="""
160+
[z3c.autoinclude.plugin]
161+
target = plone
162+
"""
163+
```
164+
165+
When your package name differs from your module name, so what you import in Python, you need a different entry point.
166+
When your module is called `example.alternative`, create this entry point:
167+
168+
```
169+
entry_points="""
170+
[plone.autoinclude.plugin]
171+
target = plone
172+
module = example.alternative
173+
"""
174+
```
175+
176+
A second change that may influence add-ons, is that the `includeDependencies` directive is no longer supported.
177+
It was already recommended not to use this directive, as it is too implicit.
178+
In the zcml files of your add-on, search for `includeDependencies`.
179+
If you find it, you must replace it by explicitly loading any zcml from other packages that the add-on needs.
180+
Sample change from [`dexterity.membrane`](https://github.com/collective/dexterity.membrane/pull/60):
181+
182+
```
183+
- <includeDependencies package="." />
184+
+ <include package="Products.membrane" />
185+
```
186+
187+
The same change is needed for the no longer supported `includeDependenciesOverrides` directive, which may be used in `overrides.zcml`.
188+
189+
See [PLIP 3339](https://github.com/plone/Products.CMFPlone/issues/3339).
190+
Also see the [`plone.autoinclude`](https://github.com/plone/plone.autoinclude) documentation.

0 commit comments

Comments
 (0)