Merge pull request #1628 from plone/fixyarninstallation2

Fix yarn installation

Author: stevepiercy

docs/conf.py

@@ -130,9 +130,11 @@
     "plone.restapi/performance",
     "plone.restapi/src",
     "volto/contributing/branch-policy.md",
-    "volto/contributing/install-operating-system.md",
-    "volto/contributing/install-nodejs.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 = [

docs/glossary.md

@@ -280,7 +280,17 @@ mrs-developer
     As a byproduct of its update operations, it also automatically adjusts `jsconfig.json`, which is used by Volto to configure webpack aliases.
 
 Yarn
-    [Yarn](https://yarnpkg.com/) is a JavaScript package manager.
+    [Yarn](https://yarnpkg.com/) is both a JavaScript package manager and project manager.
+
+Corepack
+    [Corepack](https://github.com/nodejs/corepack) is a zero-runtime-dependency Node.js script that acts as a bridge between Node.js projects and the package managers they are intended to be used with during development.
+    In practical terms, Corepack lets you use {term}`Yarn`, {term}`npm`, and {term}`pnpm` without having to install them.
+
+    Corepack is distributed by default with all recent Node.js versions.
+    Run `corepack enable` to install the required Yarn and pnpm binaries on your path.
+
+Git
+    [Git](https://git-scm.com/) is a free and open source distributed version control system.
 
 Hydration
     After loading an HTML page generated with {term}`SSR` in the browser, React can populate the existing {term}`DOM` elements, and recreate and attach their coresponding components.

docs/install/create-project.md

@@ -11,7 +11,7 @@ myst:
 (create-a-project-label)=
 
 # Create a project
- 
+
 This chapter describes how you can create a web application project using Plone, with full control over development and deployment.
 
 If instead you want to contribute to a Plone package, see {doc}`/contributing/index`.
@@ -64,6 +64,7 @@ To avoid RAM and disk swap limitations, we recommend either temporarily resizing
 -   {term}`Yarn`
 -   {term}`GNU make`
 -   {term}`Docker`
+-   {term}`Git`
 
 
 (install-prerequisites-python-label)=
@@ -134,48 +135,44 @@ For the `fish` shell, see [`nvm.fish`](https://github.com/jorgebucaran/nvm.fish)
 
 (install-prerequisites-yeoman-label)=
 
-#### Yeoman
+#### Yeoman and the Volto boilerplate generator
 
-Install {term}`Yeoman`.
+Install {term}`Yeoman` and the Volto boilerplate generator.
 
 ```shell
-npm install -g yo
+npm install -g yo @plone/generator-volto
 ```
 
 
 (install-prerequisites-yarn-label)=
 
-#### Yarn 3
+#### Yarn
 
-Install the latest Yarn 3 version (not the Classic 1.x one).
+Use {term}`Corepack` to enable Yarn, which was already installed with the {ref}`supported version of Node.js <install-packages-prerequisites-label>`.
 
 1.  Open a terminal and type:
 
     ```shell
     corepack enable
     ```
 
-2.  Verify that Yarn v3.x.x is installed and activated.
+````{important}
+The preceding instructions will not work if you have used another package manager, such as Homebrew on macOS, to install Yarn.
+You can verify where you installed Yarn.
 
-    ```shell
-    yarn set version 3.x
-    yarn -v
-    ```
-    ```console
-    3.2.3
-    ```
+```shell
+which yarn
+# /opt/homebrew/bin/yarn
+```
 
-    If you see a version that is not v3.x.x, you can try deleting the {file}`yarn.lock` file, and installing again.
+If the console includes `homebrew` in the path, then you must uninstall it.
 
-    ```shell
-    rm yarn.lock
-    corepack enable
-    yarn set version 3.x
-    yarn -v
-    ```
-    ```console
-    3.2.3
-    ```
+```shell
+brew uninstall yarn
+```
+
+Now the instructions to install Yarn should work.
+````
 
 
 (install-prerequisites-make-label)=
@@ -188,12 +185,20 @@ Install the latest Yarn 3 version (not the Classic 1.x one).
 
 (install-prerequisites-docker-label)=
 
-#### Install Docker
+#### Docker
 
 ```{include} ../volto/contributing/install-docker.md
 ```
 
 
+(install-prerequisites-git-label)=
+
+#### Git
+
+```{include} ../volto/contributing/install-git.md
+```
+
+
 (install-packages-install-label)=
 
 ## Install Plone 6
@@ -234,7 +239,7 @@ Note that pip normalizes these names, so `plone.volto` and `plone-volto` are the
 % pipx run cookiecutter gh:collective/cookiecutter-plone-starter
 
 
-Cookiecutter Plone Starter 
+Cookiecutter Plone Starter
 ================================================================================
 
 Sanity checks
@@ -249,46 +254,46 @@ Project details
 --------------------------------------------------------------------------------
 
   [1/19] Project Title (Project Title): Plone Conference Website 2070
-  [2/19] Project Description (A new project using Plone 6.): 
-  [3/19] Project Slug (Used for repository id) (plone-conference-website-2070): 
-  [4/19] Project URL (without protocol) (plone-conference-website-2070.example.com): 
+  [2/19] Project Description (A new project using Plone 6.):
+  [3/19] Project Slug (Used for repository id) (plone-conference-website-2070):
+  [4/19] Project URL (without protocol) (plone-conference-website-2070.example.com):
   [5/19] Author (Plone Foundation): Elli
   [6/19] Author E-mail ([email protected]): [email protected]
-  [7/19] Python Package Name (plone_conference_website_2070): 
-  [8/19] Volto Addon Name (volto-plone-conference-website-2070): 
+  [7/19] Python Package Name (plone_conference_website_2070):
+  [8/19] Volto Addon Name (volto-plone-conference-website-2070):
   [9/19] Choose a Python Test Framework
     1 - pytest
     2 - unittest
-    Choose from [1/2] (1): 
-  [10/19] Plone Version (6.0.8): 
+    Choose from [1/2] (1):
+  [10/19] Plone Version (6.0.8):
   [11/19] Should we use Volto Alpha Versions? (No): yes
-  [12/19] Volto Version (18.0.0-alpha.1): 
-  [13/19] Volto Generator Version (8.0.0): 
+  [12/19] Volto Version (18.0.0-alpha.1):
+  [13/19] Volto Generator Version (8.0.0):
   [14/19] Language
     1 - English
     2 - Deutsch
     3 - Español
     4 - Português (Brasil)
     5 - Nederlands
     6 - Suomi
-    Choose from [1/2/3/4/5/6] (1): 
+    Choose from [1/2/3/4/5/6] (1):
   [15/19] GitHub Username or Organization (collective): ellizurigo
   [16/19] Container Registry
     1 - GitHub Container Registry
     2 - Docker Hub
-    Choose from [1/2] (1): 
+    Choose from [1/2] (1):
   [17/19] Should we setup a caching server?
     1 - Yes
     2 - No
     Choose from [1/2] (1): 2
   [18/19] Add Ansible playbooks?
     1 - Yes
     2 - No
-    Choose from [1/2] (1): 
+    Choose from [1/2] (1):
   [19/19] Add GitHub Action to Deploy this project?
     1 - Yes
     2 - No
-    Choose from [1/2] (1): 
+    Choose from [1/2] (1):
 
 Plone Conference Website 2070 generation
 --------------------------------------------------------------------------------
@@ -358,7 +363,7 @@ To fix this you could try to:
 1. loosen the range of package versions you've specified
 2. remove package versions to allow pip attempt to solve the dependency conflict
 
-ERROR: ResolutionImpossible: for help visit 
+ERROR: ResolutionImpossible: for help visit
 make[2]: *** [Makefile:112: build-dev] Error 1
 make[2]: Leaving directory '/home/username/projects/volto/plone-volto/backend'
 make[1]: *** [Makefile:46: install-backend] Error 2