Skip to content

Commit 16f3bb4

Browse files
mauritsvanreesstevepiercyMrTangodavisagli
authored
Document distributions in the 6.1 upgrade guide. (#1733)
* Document distributions in the 6.1 upgrade guide. See plone/Products.CMFPlone#3854 * Review of Distributions documentation * Align term definition with upgrade guide docs, avoiding circular reference. * Fix admonition syntax * Add link to repo * Enhance screenshot with card syntax * plone.exportimport is not for upgrading Plone. If you need an export/import for upgrading Plone you would still use collective.exportimport. Upgrading is not a use case that plone.exportimport covers. * Here we do not start a new project, I just mean: start Plone. * These are not 'frontend distributions'. * Creating a 6.1 CMFPlone site differs from 6.0, that is the main point here. * Don't mention installing add-ons here, activating is enough. Sure, the Python package of an add-on must be installed before you can activate it, but the same is true for a distribution. The plone.classicui distribution has basically the same Python package dependencies as CMFPlone, although it activates a few extra ones automatically if they are available (say plone.app.caching). * reorganize distribution docs * Apply suggestions from code review * Update conceptual guide for distributions, where the significant changes are: - Use the actual package names of the built-in distributions - Move the comparison to other CMSs to the end of the page, putting Plone-only content first. * Create an entry in `index.md` to include a new `developer-guide/index.md` and the new `developer-guide/create-a-distribution.md` * Update glossary reference to other distribution material * Add cross-reference * Add JSON Schema to Glossary * Tidy up create-a-distribution.md. - Rewrite passive voice to active. - Enhance code blocks with `emphasize-lines`. - Use definition lists as appropriate for terms and inline literals. - Add links and terms where helpful. * Revert distribution names and enhance `ALLOWED_DISTRIBUTIONS` usage. * Tidy up add-site.md, mostly docs style guide stuff, and a rewording of the final admonition. Add plural `distributions` to Glossary. * Tidy up distributions section in upgrade-to-61.md * Update docs/backend/upgrading/version-specific-migration/upgrade-to-61.md Co-authored-by: David Glick <[email protected]> * Move add-site into Admin Guide. Move Admin Guide before Developer Guide in main navigation * Remove stray characters from bad merge * Resolve TODOs by moving file and adding link to new choose-user-interface. * Update glossary with Zope instance and cross-references to Zope itself. * Fix cross-references * Fix link * Ignore link to static images * Ignore searches on GitHub as it rate limits and times out. * Update docs/developer-guide/index.md Co-authored-by: David Glick <[email protected]> --------- Co-authored-by: Steve Piercy <[email protected]> Co-authored-by: Maik Derstappen <[email protected]> Co-authored-by: David Glick <[email protected]>
1 parent 55c4483 commit 16f3bb4

File tree

12 files changed

+584
-9
lines changed

12 files changed

+584
-9
lines changed

‎docs/admin-guide/add-site.md

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
---
2+
myst:
3+
html_meta:
4+
"description": "How to add a Plone site to an existing Zope instance"
5+
"property=og:description": "How to add a Plone site to an existing Zope instance"
6+
"property=og:title": "Add a Plone site"
7+
"keywords": "Plone 6, create, add, factory, distributions"
8+
---
9+
10+
(add-a-plone-site-label)=
11+
12+
# Add a Plone site
13+
14+
This section explains how to add a Plone site to an existing Zope instance.
15+
It assumes that you have already {doc}`installed </install/index>` and started Plone.
16+
17+
Some installation methods create a Plone site for you already.
18+
Follow these instructions if you used an installation method that did not do this, or if you need a second Plone site in the same instance for some reason.
19+
20+
```{versionadded} Plone 6.1
21+
The user interface for creating a new Plone site was changed in Plone 6.1.
22+
You can access it the same way in Plone 6.0, but the appearance and options are different.
23+
```
24+
25+
Visit the Plone backend in a web browser.
26+
Usually it is running at http://localhost:8080/.
27+
28+
The launch screen prompts you to choose one of the available {term}`distributions` to create a new site.
29+
You can read {doc}`/conceptual-guides/choose-user-interface` to help inform your choice between Volto and Classic UI.
30+
31+
````{card}
32+
```{image} /backend/upgrading/version-specific-migration/images/distribution-chooser.png
33+
:alt: Launch screen for choosing a distribution
34+
:target: /_images/distribution-chooser.png
35+
```
36+
+++
37+
_Launch screen for choosing a distribution_
38+
````
39+
40+
Hover over your choice and click the {guilabel}`Create` button.
41+
42+
Now complete the form with initial configuration for your site.
43+
You can configure the following settings.
44+
45+
Path Identifier
46+
: The ID of the site.
47+
This ends up as part of the URL unless hidden by an upstream web server.
48+
49+
Title
50+
: The name of the site in the HTML `title` element.
51+
This will be shown as part of the title of the browser tab on each page.
52+
53+
Site Description
54+
: A brief description that will be served in an HTML `meta` tag.
55+
56+
Site Logo
57+
: Upload an image as the main site logo.
58+
59+
Language
60+
: The main language of the site.
61+
62+
Timezone
63+
: The default timezone setting of the portal.
64+
65+
Finally, click the {guilabel}`Submit` button.
66+
67+
Have fun with your new Plone site!
68+
69+
```{important}
70+
The launch screen for adding a site is hosted by the Plone backend server.
71+
Regardless of the frontend you select, you will be redirected to the backend's user interface after you create the site.
72+
If you select the Volto frontend, you can switch to it by changing the port number in the URL, usually `3000`, and visiting it at http://localhost:3000, for example.
73+
```

‎docs/admin-guide/index.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ install-pip
2929
:maxdepth: 1
3030
3131
run-plone
32+
add-site
3233
configure-zope
3334
add-ons
3435
override-core

‎docs/backend/upgrading/version-specific-migration/images/distribution-chooser.png

106 KB
Loading

‎docs/backend/upgrading/version-specific-migration/upgrade-to-61.md

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -136,3 +136,44 @@ If you have an existing Plone 5.2 or 6.0 site and you migrate to 6.1, then migra
136136
- If the `plone.app.discussion` Python package is _not_ in your setup, but the site has existing comments (discussions), then the migration code stops with an error.
137137
Apparently you _were_ using comments in your site.
138138
Add the `plone.app.discussion` package to your dependencies, and run the migration again.
139+
140+
141+
## Distributions
142+
143+
Plone 6.1 introduces the concept of a Plone {term}`distribution`.
144+
A Plone distribution is a Python package that defines specific features, themes, add-ons, and configurations that get activated when creating a Plone site.
145+
Now it is available in core Plone as the recommended way for {doc}`creating a new Plone site </admin-guide/add-site>`.
146+
147+
```{seealso}
148+
For more information about distribution concepts, see {doc}`/conceptual-guides/distributions`.
149+
```
150+
151+
Distributions are optional.
152+
If your project only uses the `Products.CMFPlone` Python package, you can still create a Plone site in the old way.
153+
Consider, however, that doing so you will have the following differences when compared to using distributions.
154+
155+
- The configuration form is simpler and shorter.
156+
- The created site has no content, and therefore no {guilabel}`News` or {guilabel}`Events` folders.
157+
- You must activate add-ons through the {guilabel}`Add-ons` control panel.
158+
159+
There are a few things you should consider when upgrading a project to, or making an add-on compatible with, Plone 6.1.
160+
161+
- In general, you don't need to change anything.
162+
Your existing site will keep working.
163+
But adding a new site may change in the ways described earlier.
164+
- Do you want to use the `Products.CMFPlone` package (no distributions), either `plone.volto` or `plone.classicui` (one distribution), or `Plone` (two distributions)?
165+
- If your site uses Volto for the frontend, you will already have `plone.volto` as a dependency.
166+
This can stay the same.
167+
- If your site depends on the `Products.CMFPlone` package without the `Plone` or `plone.volto` packages, then the frontend is Classic UI.
168+
This can stay the same, but you may want to depend on `plone.classicui`.
169+
With that package you can still create a new site and have the same content as before.
170+
- If your site uses the `Plone` package, you will have the two new distributions available.
171+
This is fine.
172+
If you know you only need `plone.volto` or only need `plone.classicui`, you can switch to only one or the other.
173+
You can also limit the options for selecting a distribution by setting the environment variable `ALLOWED_DISTRIBUTIONS` with fewer options.
174+
Set `ALLOWED_DISTRIBUTIONS=default` for the distribution targeting the Volto frontend (`plone.volto`).
175+
Set `ALLOWED_DISTRIBUTIONS=classic` for the distribution with the Classic UI frontend (`plone.classicui`).
176+
- If you switch from `Plone` to `plone.volto` or `plone.classicui`, you might want to install extra core add-ons, for example `plone.app.upgrade` or `plone.app.caching`.
177+
- If your add-on is only for Volto, you might want to add `plone.volto` as a dependency.
178+
- If your add-on is only for Classic UI, you might want to add `plone.classicui` as a dependency.
179+
Note though that `plone.classicui` is not available for Plone 6.0.

‎docs/conceptual-guides/distributions.md

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
---
2+
myst:
3+
html_meta:
4+
"description": "A Plone distribution is a pre-packaged version of Plone that includes specific features, themes, modules, and configurations."
5+
"property=og:description": "A Plone distribution is a pre-packaged version of Plone that includes specific features, themes, modules, and configurations."
6+
"property=og:title": "Plone distributions"
7+
"keywords": "Plone 6, distribution, plone.distribution"
8+
---
9+
10+
(plone-distributions-label)=
11+
12+
# Plone distributions
13+
14+
```{versionadded} Plone 6.1
15+
```
16+
17+
A Plone {term}`distribution` is a pre-packaged version of Plone that includes specific features, themes, modules, and configurations.
18+
It is a convenient way to get a specific type of website up and running quickly, as the distribution includes everything needed to run that type of site.
19+
20+
```{seealso}
21+
To create your own distribution, see {doc}`/developer-guide/create-a-distribution`.
22+
```
23+
24+
25+
## Built-in distributions
26+
27+
Plone comes with two built-in distributions, which correspond to the two Plone user interfaces.
28+
29+
[`plone.volto`](https://github.com/plone/plone.volto)
30+
: Create a Plone site with the Volto frontend.
31+
32+
[`plone.classicui`](https://github.com/plone/plone.classicui)
33+
: Create a Plone site with the Classic UI frontend.
34+
35+
36+
## Third-party distributions
37+
38+
You can create your own distributions to suit your needs.
39+
40+
```{seealso}
41+
For a how-to guide, see {doc}`/developer-guide/create-a-distribution`.
42+
```
43+
44+
For example, a Plone consulting agency can create a distribution demonstrating its favorite setup for Plone.
45+
This would contain the add-ons that they usually add in each project, including example content.
46+
With this, the agency can create a fully configured Plone site filled with content for a potential client.
47+
48+
Alternatively, an agency or implementer can create a distribution for specific project.
49+
This could create a site with all add-ons activated and configured for this project, including example content, and optionally users and groups.
50+
During the development phase of a new project, all developers would use this to create a fresh site locally so that everyone has the same configuration and content.
51+
52+
Custom Plone distributions can be distributions for use by others.
53+
Examples of third-party Plone distributions include:
54+
55+
- [SENAITE](https://www.senaite.com)
56+
- [Quaive](https://quaive.com/)
57+
- [Portal Modelo](https://www.interlegis.leg.br/produtos-servicos/portal-modelo/)
58+
- [Portal Padrão](https://identidade-digital-de-governo-plone.readthedocs.io/en/latest/)
59+
60+
61+
## Related packages
62+
63+
The implementation of distributions in the Plone codebase is found in the following Python packages.
64+
65+
- [`plone.distribution`](https://github.com/plone/plone.distribution) provides the framework for defining distributions.
66+
- [`plone.exportimport`](https://github.com/plone/plone.exportimport) imports and exports content, users, and other objects between Plone sites.
67+
`plone.distribution` uses it.
68+
- [`plone.volto`](https://github.com/plone/plone.volto) is the distribution to create a Plone site with the Volto frontend.
69+
- [`plone.classicui`](https://github.com/plone/plone.classicui) is the distribution to create a Plone site with the Classic UI frontend.
70+
71+
```{note}
72+
For Plone 7, the [Plone roadmap](https://plone.org/why-plone/roadmap) guides development toward a clearer separation between the Classic UI frontend and the core `Products.CMFPlone` backend.
73+
This means that in Plone 7, `Products.CMFPlone` will have less code and pull in fewer dependencies, whereas `plone.classicui` may have more code and pull in more dependencies.
74+
This is the direction in which the backend is heading, and the introduction of the `plone.classicui` distribution package is an important step along this path.
75+
```
76+
77+
## Comparison with other CMSs
78+
79+
Drupal
80+
: Drupal has distributions for blogs, e-commerce sites, and intranet portals.
81+
82+
WordPress
83+
: WordPress has a similar concept in the form of "WordPress Multisite," which allows users to run multiple websites from a single installation of WordPress.
84+
85+
Joomla
86+
: Joomla has a similar concept in the form of "Joomla Templates," which are pre-designed templates for Joomla websites.
87+
88+
TYPO3
89+
: TYPO3 has a similar concept in the form of "TYPO3 Distributions," which are pre-configured installations of TYPO3 for specific types of websites.

‎docs/conceptual-guides/index.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ This part of the documentation provides explanation of concepts to deepen and br
1616
:maxdepth: 2
1717
1818
choose-user-interface
19+
distributions
1920
package-management
2021
make-build-backend-walk-through
2122
```

‎docs/conceptual-guides/make-build-backend-walk-through.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,7 @@ The command `make build-backend`:
5252

5353
- Returning to the target `build-dev`:
5454

55-
- This generates the `mxdev` files as described above in {ref}`mxdev-usage-overview-label`.
55+
- This generates the `mxdev` files as described above in {ref}`manage-backend-python-packages-label`.
5656
- Installs Plone core packages and add-ons from the files generated by `mxdev`.
5757

5858
You can configure your Zope instance as described in the section {doc}`/admin-guide/configure-zope`.

‎docs/conf.py

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -82,15 +82,18 @@
8282
r"http://127.0.0.1",
8383
r"http://localhost",
8484
r"http://yoursite",
85-
# Ignore file downloads
85+
# Ignore static file downloads
8686
r"^/_static/",
87+
r"^/_images/",
8788
# Ignore pages that require authentication
8889
r"https://github.com/orgs/plone/teams/", # requires auth
8990
r"https://github.com/plone/documentation/issues/new/choose", # requires auth
9091
r"https://github.com/plone/volto/issues/new/choose", # requires auth
9192
r"https://opensource.org/", # requires auth
9293
# Ignore github.com pages with anchors
9394
r"https://github.com/.*#.*",
95+
# Ignore github.com searches
96+
r"https://github.com/search",
9497
# Ignore other specific anchors
9598
r"https://coveralls.io/repos/github/plone/plone.restapi/badge.svg\?branch=main", # plone.restapi
9699
r"https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS/Errors#Identifying_the_issue",

0 commit comments

Comments
 (0)