Merge branch '6.0' into classic-ui-autoforms

Author: stevepiercy

.github/ISSUE_TEMPLATE/new-issue-form.yml

@@ -17,6 +17,6 @@ body:
     id: description
     attributes:
       label: Description
-      description: Include include screenshots and any other helpful information.
+      description: Include screenshots and any other helpful information.
     validations:
       required: true

.github/workflows/build_deploy.yml

@@ -5,6 +5,9 @@ on:
     branches:
       - "6.0"
 
+env:
+  node-version: 20.x
+
 jobs:
   build_deploy:
     runs-on: ubuntu-latest
@@ -35,31 +38,32 @@ jobs:
       - name: Prepare deploy
         run: make deploy
 
-      # node setup
-      - name: Use Node.js 16
+      - name: Use Node.js ${{ env.node-version }}
         uses: actions/setup-node@v3
         with:
-          node-version: '16'
-      - name: Install Yarn
-        run: npm install -g yarn
-      # node cache
-      - name: Get yarn cache directory path
-        id: yarn-cache-dir-path
-        working-directory: submodules/volto
-        run: echo "dir=$(yarn config get cacheFolder)" >> $GITHUB_OUTPUT
+          node-version: ${{ env.node-version }}
+
+      - uses: pnpm/action-setup@v2
+        name: Install pnpm
+        with:
+          version: 8
+          run_install: false
+
+      - name: Get pnpm store directory
+        shell: bash
+        run: |
+          echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV
+
       - uses: actions/cache@v3
-        id: yarn-cache # use this to check for `cache-hit` (`steps.yarn-cache.outputs.cache-hit != 'true'`)
+        name: Setup pnpm cache
         with:
-          path: ${{ steps.yarn-cache-dir-path.outputs.dir }}
-          key: ${{ runner.os }}-yarn-${{ hashFiles('**/yarn.lock') }}
+          path: ${{ env.STORE_PATH }}
+          key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
           restore-keys: |
-            ${{ runner.os }}-yarn-
+            ${{ runner.os }}-pnpm-store-
 
       - name: StoryBook build
-        run: |
-          cd submodules/volto 
-          yarn install --immutable 
-          yarn build-storybook -o ../../_build/html/storybook
+        run: make storybook
 
       - name: Deploy to server
         id: deploy

Makefile

@@ -7,8 +7,8 @@ SPHINXOPTS      ?=
 PAPER           ?=
 
 # Internal variables.
-SPHINXBUILD     = $(realpath bin/sphinx-build)
-SPHINXAUTOBUILD = $(realpath bin/sphinx-autobuild)
+SPHINXBUILD     = "$(realpath bin/sphinx-build)"
+SPHINXAUTOBUILD = "$(realpath bin/sphinx-autobuild)"
 DOCS_DIR        = ./docs/
 BUILDDIR        = ../_build
 PAPEROPT_a4     = -D latex_paper_size=a4
@@ -196,8 +196,8 @@ linkcheckbroken: deps  ## Run linkcheck and show only broken links
 
 .PHONY: vale
 vale: deps  ## Run Vale style, grammar, and spell checks
-	vale sync
-	vale --no-wrap $(VALEFILES)
+	bin/vale sync
+	bin/vale --no-wrap $(VALEFILES)
 	@echo
 	@echo "Vale is finished; look for any errors in the above output."
 
@@ -235,11 +235,11 @@ netlify:
 	ln -s ../submodules/volto/docs/source ./docs/volto
 	ln -s ../submodules/plone.restapi ./docs/plone.restapi
 	ln -s ../submodules/plone.api/docs ./docs/plone.api
-	cd $(DOCS_DIR) && sphinx-build -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	cd $(DOCS_DIR) && sphinx-build -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html && cp ./netlify_robots.txt $(BUILDDIR)/html/robots.txt
 
 .PHONY: storybook
 storybook:
-	cd submodules/volto && yarn && yarn build-storybook -o ../../_build/html/storybook
+	cd submodules/volto && pnpm i && pnpm build:registry && pnpm --filter @plone/volto build-storybook -o ../../../../_build/html/storybook
 
 .PHONY: all
 all: clean vale linkcheck html  ## Clean docs build, then run vale and linkcheck, and build html

docs/_static/contributing/first-time-plone-git-workflow.svg

@@ -114,7 +114,7 @@ tag = scale_util.tag(
     scale=None,
     height=None,
     width=None,
-    direction="thumbnail"
+    mode="scale"
 )
 ```
 
@@ -233,20 +233,44 @@ image_scale = scaling_util.publishTraverse(context.REQUEST, groups[1])
 ```
 
 
-(classic-ui-images-scaling-direction-label)=
+(classic-ui-images-scaling-mode-label)=
 
-## Scaling `direction`
+## Scaling `mode`
 
-The default direction is `thumbnail`.
+```{versionchanged} 6.0
+Added `mode` to replace the deprecated `direction`.
+Added new option names for `mode` to align with CSS `background-size` values, and deprecated previous names `keep`, `thumbnail`, `scale-crop-to-fit`, `down`, `scale-crop-to-fill`, and `up`.
+```
+
+Scaling is intended for the optimal display of images in a web browser.
+
+To scale an image, you can use the `mode` parameter to control the scaling output.
+You must use either `width` or `height`, or both.
+
+Three different scaling options are supported.
+They correspond to the CSS [`background-size`](https://developer.mozilla.org/en-US/docs/Web/CSS/background-size) values.
+
+The possible options for `mode` are listed below, where the default option is `scale`.
+
+`scale`
+:   This is the default option.
+    `scale` scales to the requested dimensions without cropping.
+    The resulting image may have a different size than requested.
+    This option requires both `width` and `height` to be specified.
+    It does not scale up.
+
+    Deprecated option names: `keep`, `thumbnail`.
+
+`contain`
+:   `contain` starts by scaling the image either to the smaller dimension when you give both `width` and `height`, or to the only given dimension, then crops to the other dimension if needed.
+
+    Deprecated option names: `scale-crop-to-fit`, `down`.
 
-Other options are:
+`cover`
+:   `cover` scales the image either to the larger dimension when you give both `width` and `height`, or to the only given dimension, up to the size you specify.
+    Despite the deprecated option name, it does not crop.
 
-* `down`
-* `keep`
-* `scale-crop-to-fill`
-* `scale-crop-to-fit`
-* `thumbnail`
-* `up`
+    Deprecated option names: `scale-crop-to-fill`, `up`.
 
 
 (classic-ui-images-permissions-label)=

docs/classic-ui/images.md

@@ -53,6 +53,7 @@ forms
 icons
 images
 layers
+mockup
 portlets
 recipes
 static-resources

docs/classic-ui/index.md

@@ -0,0 +1,18 @@
+---
+myst:
+  html_meta:
+    "description": "Mockup together with Patternslib are used to build the UI toolkit for Classic UI, a frontend for Plone."
+    "property=og:description": "Mockup together with Patternslib are used to build the UI toolkit for Classic UI, a frontend for Plone."
+    "property=og:title": "Mockup"
+    "keywords": "Mockup, Patternslib, Classic UI, frontend, Plone"
+---
+
+(mockup-label)=
+
+# Mockup
+
+{term}`Mockup` together with {term}`Patternslib` are used to build the UI toolkit for {term}`Classic UI`, a frontend for Plone.
+
+View the [interactive documentation of Mockup](https://plone.github.io/mockup/).
+
+For more information, visit the [Mockup repository on GitHub](https://github.com/plone/mockup).

docs/classic-ui/mockup.md

@@ -25,7 +25,7 @@ To create an add-on package with a Plone Classic UI theme, you need to install t
 -   [Python (>=3.8)](https://www.python.org/)
 -   [plonecli](https://pypi.org/project/plonecli/)
 
-Read more about how to install pre-requisites in {doc}`/install/install-from-packages`.
+Read more about how to install pre-requisites in {doc}`/install/create-project`.
 
 
 (classic-ui-theming-barceloneta-create-a-classic-ui-theme-add-on-package-label)=

docs/classic-ui/theming/barceloneta.md

@@ -49,6 +49,7 @@
     "sphinx.ext.todo",
     "sphinx_copybutton",
     "sphinx_design",
+    "sphinx_reredirects",
     "sphinx_sitemap",
     "sphinxcontrib.httpdomain",  # plone.restapi
     "sphinxcontrib.httpexample",  # plone.restapi
@@ -92,11 +93,14 @@
     r"https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS/Errors#Identifying_the_issue",
     r"https://docs.cypress.io/guides/references/migration-guide#Migrating-to-Cypress-version-10-0",  # volto
     # Ignore unreliable sites
+    r"https://chromewebstore.google.com/detail/react-developer-tools/fmkadmapgofadopljbjfkapdkoienihi",  # TODO retest with latest Sphinx when upgrading theme. chromewebstore recently changed its URL and has "too many redirects".
+    r"https://chromewebstore.google.com/detail/redux-devtools/lmhkpmbekcpmknklioeibfkpmmfibljd",  # TODO retest with latest Sphinx when upgrading theme. chromewebstore recently changed its URL and has "too many redirects".
+    r"https://stackoverflow.com",  # volto and documentation  # TODO retest with latest Sphinx.
     r"https://web.archive.org/",  # volto
     r"https://www.youtube.com/playlist",  # volto, TODO remove after installing sphinxcontrib.youtube
 ]
 linkcheck_anchors = True
-linkcheck_timeout = 5
+linkcheck_timeout = 10
 linkcheck_retries = 1
 
 # The suffix of source filenames.
@@ -127,6 +131,11 @@
     "plone.restapi/performance",
     "plone.restapi/src",
     "volto/contributing/branch-policy.md",
+    "volto/contributing/install-docker.md",
+    "volto/contributing/install-git.md",
+    "volto/contributing/install-make.md",
+    "volto/contributing/install-nodejs.md",
+    "volto/contributing/install-operating-system.md",
 ]
 
 suppress_warnings = [
@@ -216,6 +225,16 @@
 notfound_template = "404.html"
 
 
+# -- sphinx-reredirects configuration ----------------------------------
+# https://documatt.com/sphinx-reredirects/usage.html
+redirects = {
+    "contributing/plone-api": "/plone.api/contribute/index.html",
+    "contributing/plone-restapi": "/plone.restapi/docs/source/contributing/index.html",
+    "contributing/volto": "/volto/contributing/index.html",
+    "install/install-from-packages": "/install/create-project.html",
+}
+
+
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
@@ -322,8 +341,9 @@ def source_replace(app, docname, source):
 # Dict of replacements.
 source_replacements = {
     "{PLONE_BACKEND_MINOR_VERSION}": "6.0",
-    "{PLONE_BACKEND_PATCH_VERSION}": "6.0.8",
-    "{NVM_VERSION}": "0.39.3",
+    "{PLONE_BACKEND_PATCH_VERSION}": "6.0.10.1",
+    "{NVM_VERSION}": "0.39.5",
+    "{SUPPORTED_PYTHON_VERSIONS}": "3.8, 3.9, 3.10, 3.11, or 3.12",
 }
 
 

docs/conf.py

@@ -53,15 +53,12 @@ Open `/_build/html/index.html` in a web browser.
 
 ### American English spelling, grammar, and syntax, and style guide
 
-Spellings are enforced through [`Vale`](https://vale.sh/).
+[Vale](https://vale.sh/) is a linter for narrative text.
+It checks spelling, English grammar, and style guides.
 Plone uses American English.
 
-Spelling is configured in {file}`Makefile`, {file}`.vale.ini`, and in files in `styles/Vocab/Plone/`.
-
-Authors should add new words and proper names using correct casing to {file}`styles/Vocab/Plone/accept.txt`, sorted alphabetically and case-insensitive.
-
 Vale also provides English grammar and syntax checking, as well as a Style Guide.
-We follow the [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/).
+The Plone Documentation Team selected the [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/) for its ease of use—especially for non-native English readers and writers—and attention to non-technical audiences. 
 
 To perform all these checks, run the following command.
 
@@ -74,6 +71,41 @@ We also understand that contributors might not be fluent in English.
 We encourage contributors to make a reasonable effort, and to request a review of their pull request from community members who are fluent in English to fix grammar and syntax.
 Please ask!
 
+```{note}
+More corrections to spellings and Vale's configuration are welcome by submitting a pull request.
+This is an easy way to become a contributor to Plone.
+See {ref}`authors-advanced-vale-usage-label` for details.
+```
+
+
+(authors-advanced-vale-usage-label)=
+
+#### Advanced Vale usage
+
+To have Vale check only a specific file or directory of files, you can issue [Vale commands](https://vale.sh/manual/) with options in a shell session.
+To allow this, you must either:
+
+-   activate your Python virtual environment
+-   use the virtual environment path, such as `bin/vale`
+-   install Vale using operating system's package manager
+
+The Vale `Makefile` command automatically installs Vale into your Python virtual environment—which is also created via any documentation `Makefile` commands—when you invoke it for the first time.
+
+Vale has [integrations](https://vale.sh/docs/integrations/guide/) with various IDEs.
+Integration might require installing Vale using operating system's package manager.
+
+-   [JetBrains](https://vale.sh/docs/integrations/jetbrains/)
+-   [Vim](https://github.com/dense-analysis/ale)
+-   [VS Code](https://github.com/errata-ai/vale-vscode)
+
+Plone configures Vale in three places:
+
+-   {file}`.vale.ini` is Vale's configuration file.
+    This file allows overriding rules or changing their severity.
+-   {file}`Makefile` passes options to the `vale` command, such as the files Vale checks.
+-   Plone documentation uses a custom spelling dictionary, with accepted and rejected spellings in `styles/Vocab/Plone`.
+    Authors should add new words and proper names using correct casing to {file}`styles/Vocab/Plone/accept.txt`, sorted alphabetically and case-insensitive.
+
 
 (authors-linkcheck-label)=
 
@@ -266,4 +298,5 @@ The Plone Documentation Team adopted additional guidelines.
 ## General documentation writing references
 
 -   [Write the Docs - Documentation Guide](https://www.writethedocs.org/guide/)
+-   [Creating effective technical documentation](https://developer.mozilla.org/en-US/blog/technical-writing/), Dipika Bhattacharya, Technical Writer at Mozilla Developer Network
 -   [A Guide to Em Dashes, En Dashes, and Hyphens](https://www.merriam-webster.com/grammar/em-dash-en-dash-how-to-use)