Document distributions in the 6.1 upgrade guide.

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

@@ -117,3 +117,85 @@ If you have an existing Plone 5.2 or 6.0 site and you migrate to 6.1, then migra
 -   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.
     Apparently you _were_ using comments in your site.
     Add the `plone.app.discussion` package to your dependencies, and run the migration again.
+
+
+## Distributions
+
+Plone 6.1 introduces the concept of a Plone {term}`distribution`.
+A Plone distribution is a Python package that defines specific features, themes, add-ons, and configurations that get activated when creating a Plone site.
+Now it is available in core Plone as the recommended way for creating a Plone site.
+
+When you install the [`Plone` 6.1 Python package](https://pypi.org/project/Plone/), you get several new packages and two distributions:
+
+-   [`plone.distribution`](https://github.com/plone/plone.distribution) is the new main package that offers the basis for distributions.
+-   [`plone.exportimport`](https://github.com/plone/plone.exportimport) imports and exports content, users, and other objects between Plone sites.
+    `plone.distribution` uses it.
+-   [`plone.volto`](https://github.com/plone/plone.volto) is the distribution to create a Plone site with the default frontend Volto.
+    This package was already present in Plone 6.0, but was upgraded to a distribution.
+-   [`plone.classicui`](https://github.com/plone/plone.classicui) is a new package and is the distribution to create a Plone site with the Classic UI frontend.
+
+When you start Plone, the launch screen prompts you to choose a distribution when creating a new Plone site.
+
+````{card}
+```{image} /backend/upgrading/version-specific-migration/images/distribution-chooser.png
+:alt: Launch screen for choosing a distribution
+:target: /_images/distribution-chooser.png
+```
++++
+_Launch screen for choosing a distribution_
+````
+
+After you select a distribution, you will fill out a brief form to configure your new Plone 6.1 site, similar to the process for Plone 6.0.
+
+Distributions are optional.
+If your project only uses the `Products.CMFPlone` Python package, you can still create a Plone site in the usual way.
+Consider, however, the following differences from distributions and from Plone 6.0.
+
+-   The configuration form is simpler and shorter.
+-   The created site has no content, and therefore no {guilabel}`News` or {guilabel}`Events` folders.
+-   You must activate add-ons through the {guilabel}`Add-ons` control panel.
+
+There are a few things you should consider when upgrading a project to, or making an add-on compatible with, Plone 6.1:
+
+-   In general, you don't need no change anything.
+    Your existing site will keep working.
+    But adding a new site may change in the ways described earlier.
+-   Do you want to use the `Products.CMFPlone` package (0 distributions), either `plone.volto` or `plone.classicui` (1 distribution), or `Plone` (2 distributions)?
+-   When your site used the default Volto frontend, you will already have `plone.volto` as a dependency.
+    This can stay the same.
+-   When your site uses only the `Products.CMFPlone` package, the frontend is Classic UI.
+    This can stay the same, but you may want to depend on `plone.classicui`.
+    With that package you can still create a new site and have the same content as before.
+-   When your site is using the `Plone` package, you will have the two new distributions available.
+    This is fine.
+    If you know you only need `plone.volto` or only need `plone.classicui`, you can switch to that.
+    You can also limit the options for selecting a distribution by setting the environment variable `ALLOWED_DISTRIBUTIONS` with fewer options.
+    Set `ALLOWED_DISTRIBUTIONS=default` for the distribution targeting the default Volto frontend (`plone.volto`).
+    Set `ALLOWED_DISTRIBUTIONS=classic` for the distribution with the Classic UI frontend (`plone.classicui`).
+-   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`.
+-   If your add-on is only for Volto, you may want to add `plone.volto` as a dependency.
+-   If your add-on is only for Classic UI, you may want to add `plone.classicui` as a dependency.
+    Note though that `plone.classicui` is not available for Plone 6.0.
+
+You can create your own distributions to suit your needs.
+
+-   Create a distribution demonstrating your favorite setup for Plone.
+    This would contain the add-ons that you usually add in each project, including example content.
+    With this you can create a fully configured Plone site filled with content for a potential client.
+    Or they can try it themselves if the distribution is available publicly.
+-   Create a distribution for an internal or client project.
+    This would create a site with all add-ons activated and configured for this project, including example content, and optionally users and groups.
+    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.
+    Before the project goes live, you can use the distribution to create the initial setup.
+
+```{note}
+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.
+This means in Plone 7 `Products.CMFPlone` will have less code and pull in fewer dependencies.
+`plone.classicui` may have more code and pull in more dependencies.
+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.
+```
+
+For detailed information, see the source code of the new packages.
+
+-   [`plone.distribution`](https://github.com/plone/plone.distribution/)
+-   [`plone.exportimport`](https://github.com/plone/plone.exportimport/)

docs/glossary.md

@@ -777,7 +777,7 @@ Load balancer
 CI
 continuous integration
     Continuous integration (CI) is the practice of integrating all your code changes into the main branch of a shared source code repository early and often, automatically testing each change when you commit or merge them, and automatically kicking off a build.
-    
+
     Read about Plone's {doc}`/contributing/core/continuous-integration`.
 
 CD
@@ -794,4 +794,13 @@ lazy loaded
 reference implementation
     A reference implementation is a program that implements all requirements from a corresponding specification.
     The reference implementation often accompanies a technical standard, and demonstrates what should be considered the "correct" behavior of any other implementation of it.
+
+distribution
+
+    ```{versionadded} Plone 6.1
+    ```
+
+    A Plone distribution is a Python package that defines specific features, themes, add-ons, and configurations that get activated when creating a Plone site.
+    It is available in core Plone as the recommended way for creating a Plone site.
+    [`plone.distribution`](https://github.com/plone/plone.distribution) is the main package that offers the basis for distributions.
 ```