Update readme 2022 (plone#3131)

* New updated, completed and fixed README. Update versions everywhere, more convenience commands * Changelog * Fix regression in multilingual test * Apply suggestions from Steve's code review Co-authored-by: Steve Piercy <[email protected]> Co-authored-by: Steve Piercy <[email protected]>
victorchrollo14 · Mar 10, 2022 · 448ff4d · 448ff4d
1 parent 6cbe9a2
commit 448ff4d
Show file tree

Hide file tree

Showing 8 changed files with 139 additions and 94 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -12,6 +12,9 @@
 
 ### Internal
 
+- Better Readme, updated to 2022 @sneridagh
+- Update to latest versions for Python packages @sneridagh
+
 ### Documentation
 
 - Fix broken links. @stevepiercy

diff --git a/Makefile b/Makefile
@@ -13,8 +13,8 @@ MAKEFLAGS+=--no-builtin-rules
 # Project settings
 
 INSTANCE_PORT=8080
-DOCKER_IMAGE=plone/plone-backend:5.2.6
-KGS=plone.restapi==8.21.0 plone.volto==4.0.0a3 plone.rest==2.0.0a2 plone.app.iterate==4.0.2 plone.app.vocabularies==4.3.0
+DOCKER_IMAGE=plone/plone-backend:5.2.7
+KGS=plone.restapi==8.21.2 plone.volto==4.0.0a3 plone.rest==2.0.0a3 plone.app.iterate==4.0.2 plone.app.vocabularies==4.3.0
 
 # Sphinx variables
 # You can set these variables from the command line.
@@ -173,7 +173,11 @@ start-backend: ## Start Plone Backend
 
 .PHONY: start-backend-docker
 start-backend-docker:
-	docker run -it --rm -p 8080:8080 -e SITE=Plone -e ADDONS='$(KGS)' $(DOCKER_IMAGE)
+	docker run -it --rm --name=backend -p 8080:8080 -e SITE=Plone -e ADDONS='$(KGS)' $(DOCKER_IMAGE)
+
+.PHONY: start-frontend-docker
+start-frontend-docker:
+	docker run -it --rm --name=volto --link backend -p 3000:3000 -e RAZZLE_INTERNAL_API_PATH=http://backend:8080/Plone -e RAZZLE_DEV_PROXY_API_PATH=http://backend:8080/Plone plone/plone-frontend:latest
 
 .PHONY: start-backend-docker-guillotina
 start-backend-docker-guillotina:

diff --git a/README.md b/README.md
@@ -1,36 +1,34 @@
 # Volto
 
-<img align="right" width="300" alt="Volto png" src="./logos/volto-colorful.png" />
+<img align="right" width="300" alt="Volto logo png" src="./logos/VoltoLogoEra2.png#gh-light-mode-only" />
+<img align="right" width="300" alt="Volto logo png" src="./logos/VoltoLogoEra2-dark-mode.png#gh-dark-mode-only" />
 
 [![NPM](https://img.shields.io/npm/v/@plone/volto.svg)](https://www.npmjs.com/package/@plone/volto)
 [![Build Status Core](https://github.com/plone/volto/actions/workflows/core.yml/badge.svg)](https://github.com/plone/volto/actions)
 [![Build Status Docs](https://github.com/plone/volto/actions/workflows/docs.yml/badge.svg)](https://github.com/plone/volto/actions)
 
 ## Introduction
 
-[Volto](https://github.com/plone/volto) is a React-based frontend for content
-management systems, currently supporting three backend implementations: Plone,
-Guillotina and a NodeJS reference implementation.
+[Volto](https://github.com/plone/volto) is a ReactJS-based frontend for the [Plone](https://plone.org) Content Management System. It will become the default UI for the upcoming Plone 6 release.
 
-[Plone](https://plone.org) is a CMS built on Python with over 20 years of history and experience.
+[Plone](https://plone.org) is a CMS built on Python with more than 20 years of history and experience.
 
 Plone has very interesting features that appeal to developers and users alike,
 such as customizable content types, hierarchical URL object traversing and a
 sophisticated content workflow powered by a granular permissions model. This
 allows you to build anything from simple websites to enterprise-grade
 intranets.
 
-Volto exposes all these features and communicates with Plone via its
-mature [REST API](https://github.com/plone/plone.restapi). Volto has the
-ability of being highly themable and customizable.
+Volto exposes all these features and communicates with Plone via its [REST API](https://github.com/plone/plone.restapi).
+Volto has the ability of being easily extensible, themeable, and customizable.
 
-Volto also supports other APIs like [Guillotina](https://guillotina.io/), a
-Python resource management system, inspired by Plone and using the same basic
-concepts like traversal, content types and permissions model.
+It features the Pastanaga editor, a modern block-based content layout editor. It is extensible and customizable, so you can adapt the default blocks provided to match your requirements, or build new ones to cover them.
 
-Last but not least, it also supports a [Volto Nodejs-based backend reference](https://github.com/plone/volto-reference-backend) API implementation that
-demos how other systems could also use Volto to display and create content
-through it.
+Volto is extensible using add-ons.
+You can build your own or choose from the community released ones:
+
+- [Volto Add-ons in NPM](https://www.npmjs.com/search?q=keywords%3Avolto-addon%2Cvolto)
+- [Volto Awesome](https://github.com/collective/awesome-volto)
 
 ## Demo
 
@@ -56,7 +54,7 @@ First get all the requirements installed on your system.
 
 - [Node.js LTS (16.x)](https://nodejs.org/)
 - [Python 3.8.x](https://python.org/) or
-- [Docker](https://www.docker.com/get-started) (if using the Plone/Guillotina docker images)
+- [Docker](https://www.docker.com/get-started) (if using the Plone docker images)
 
 ### Create a Volto project using the generator
 
@@ -74,8 +72,6 @@ follow the prompts questions, provide `myvoltoproject` as project name then, whe
 
 ### Bootstrap the Plone API backend
 
-We recommend Plone as backend of choice for Volto.
-
 You can bootstrap a ready Docker Plone container with all the dependencies and ready for Volto use. We recommend to use the Plone docker builds based in `pip` [plone/plone-backend](https://github.com/plone/plone-backend) image:
 
 ```shell
@@ -98,13 +94,13 @@ For the Plone 5 series latest released version (with Python 3) and above is reco
 
 The following KGS (or above) are also recommended, for any Plone version used.
 
-#### KGS (known good versions) for backend packages
+#### KGS (known good set of versions) for backend packages
 
 Volto always works best with latest versions of the "Frontend stack" or at least the recommended ones (in parenthesis) which are:
 
-- plone.restapi (8.18.0)
-- plone.rest (2.0.0a1)
-- plone.volto (3.1.0a7)
+- plone.restapi (8.21.2)
+- plone.rest (2.0.0a3)
+- plone.volto (4.0.0a3)
 
 and the following core packages since some features require up to date versions:
 
@@ -167,7 +163,7 @@ Please create a new [issue](https://github.com/plone/volto/issues/new) or [pull
 
 ## Documentation
 
-You can find the documentation in [https://docs.voltocms.com](https://docs.voltocms.com)
+You can find the latest (in-progress) documentation in [https://6.dev-docs.plone.org/](https://6.dev-docs.plone.org/volto/index.html)
 
 ## Training
 
@@ -222,14 +218,14 @@ JavaScript-centered trainings.
 
 ## Browser support
 
-Volto works well with any modern (and updated) browser, including their mobile
+Volto works well with any modern (evergreen) browser, including their mobile
 flavors: Chrome, Firefox, Safari, Edge.
 
-We do not guarantee that browsers who were deprecated by their vendors (e.g. Internet Explorer 11) will be supported by Volto in the future.
+We do not guarantee that deprecated browsers (e.g., Internet Explorer 11) are supported by Volto. Although proven possible, it's too great an effort to maintain. It is left to the integrator to provide support for it.
 
 ## Upgrades
 
-You can find the upgrade guide here: https://docs.voltocms.com/upgrade-guide/
+You can find the upgrade guide here: https://6.dev-docs.plone.org/volto/upgrade-guide/index.html
 
 ## Volto Development
 
@@ -248,14 +244,12 @@ git clone https://github.com/plone/volto.git
 yarn
 ```
 
-### Install a backend
-
-#### Plone (recommended)
+### Install Plone backend
 
-Either using a Docker image
+Either using a Docker command:
 
 ```shell
-docker run -it --rm --name=plone -p 8080:8080 -e SITE=Plone -e ADDONS="plone.volto" -e ZCML="plone.volto.cors" -e PROFILES="plone.volto:default-homepage" plone
+docker run -it --rm --name=backend -p 8080:8080 -e SITE=Plone -e ADDONS="plone.restapi==8.21.2 plone.app.iterate==4.0.2 plone.rest==2.0.0a3 plone.app.vocabularies==4.3.0 plone.volto==4.0.0a3" -e PROFILES="plone.volto:default-homepage" plone/plone-backend
 ```
 
 or using the convenience makefile command:
@@ -272,36 +266,24 @@ Installation Documentation](https://docs.plone.org/manage/installing/installatio
 make build-backend
 ```
 
-#### Guillotina (experimental)
+### Run frontend
 
-It still doesn't support the full API/features that Plone provides.
+Either using a Docker command:
 
 ```shell
-docker-compose -f g-api/docker-compose.yml up -d
+docker run -it --rm --name=volto --link backend -p 3000:3000 -e RAZZLE_INTERNAL_API_PATH=http://backend:8080/Plone -e RAZZLE_DEV_PROXY_API_PATH=http://backend:8080/Plone plone/plone-frontend:latest
 ```
 
 or using the convenience makefile command:
 
 ```shell
-make start-backend-docker-guillotina
-```
-
-### Run frontend
-
-Either using Docker
-
-```shell
-docker run -it --rm --name=volto --link plone -p 3000:3000 plone/volto
-
-# or with Volto add-ons enabled:
-
-docker run -it --rm --name=volto --link plone -e ADDONS="volto-testaddon volto-slate:asDefault" -p 3000:3000 plone/volto
+make start-frontend-docker
 ```
 
-or using the convenience yarn command:
+or from the local repository code:
 
 ```shell
-yarn start
+yarn && yarn start
 ```
 
 ### Browsing
@@ -339,59 +321,55 @@ a dry-release command for testing the output is also available:
 yarn dry-release
 ```
 
-### Acceptance testing
-
-Volto uses [Cypress](https://www.cypress.io/) for browser-based acceptance testing.
-
-Run acceptance tests (with the Plone backend):
+and alpha release can also be cut using:
 
 ```shell
-yarn ci:cypress:run
+yarn release-alpha
 ```
 
-Run acceptance tests (with the Guillotina backend):
+### Acceptance testing
 
-```shell
-yarn ci:cypress:run:guillotina
-```
+Volto uses [Cypress](https://www.cypress.io/) for browser-based acceptance testing.
 
-#### Writing new acceptance tests
+There are a number of fixtures available covering all the configuration use cases. These fixtures have both a specific backend and frontend configuration setup and a related set of tests. The CI infrastructure runs them all automatically on every push to a branch or PR.
 
-When writing new acceptance tests you usually want to minimize the time it takes to run the tests.
+The tests can be run in headless mode (same as the CI does), or within the Cypress user interface. The latter is the one that you run under development.
 
-To do so, start three individual terminal sessions for running the Plone backend, the Volto frontend and the acceptance tests.
+### How to run acceptance tests locally (during development)
 
-Start the Plone backend:
+When writing new acceptance tests, you usually want to minimize the time it takes to run the tests, while also being able to debug or inspect what's going on.
 
-```shell
-make start-test-backend
-```
+To do so, start three individual terminal sessions for running the Plone backend, the Volto frontend, and the acceptance tests.
 
-Start the Volto frontend:
+1.  Run the backend fixture
+    ```shell
+    make test-acceptance-server
+    ```
+2.  Run the frontend fixture
+    ```shell
+    yarn cypress:start-frontend
+    ```
+3.  Run the Cypress tests for that fixture
+    ```shell
+    yarn cypress:open
+    ```
 
-```shell
-make start-test-frontend
-```
+Available fixtures:
 
-Open Cypress and start acceptance tests:
+- Core (core or not special naming in the test commands)
+- Multilingual (multilingual)
+- Working Copy (workingCopy)
+- Core Sandbox (coresandbox)
 
-```shell
-make start-test
-```
+There are convenience commands for each of these fixtures. See `package.json` or `.github` CI setup for more information.
 
-Go to the `cypress/integration` folder to see existing tests.
+#### Writing new acceptance tests
+
+Go to the `cypress/tests` folder to see existing tests. There is a directory per fixture.
 This directory is hot reloaded with your changes as you write the tests. For more information on how to write Cypress tests:
 
     https://docs.cypress.io
 
-#### Running the acceptance tests with Guillotina backend
-
-If you want to use Guillotina as backend to run the tests you should run:
-
-```shell
-yarn ci:start-api-plone-guillotina
-```
-
 ## Translations
 
 If you would like contribute to translate Volto into several languages, please, read the [Internationalization (i18n) guide](https://docs.voltocms.com/customizing/i18n/).
@@ -402,6 +380,38 @@ If you would like contribute to translate Volto into several languages, please,
   <img src="https://contrib.rocks/image?repo=plone/volto" />
 </a>
 
+## Alternative backends
+
+Volto also supports other APIs like [Guillotina](https://guillotina.io/), a
+Python resource management system, inspired by Plone and using the same basic
+concepts like traversal, content types, and permissions model.
+
+Last but not least, it also supports a [Volto Node.js-based backend reference](https://github.com/plone/volto-reference-backend) API implementation that
+demos how other systems could also use Volto to display and create content
+through it.
+
+### Run a Guillotina backend
+
+*Disclaimer:* Guillotina doesn't support the full API/features that Plone provides. Contributors are welcome.
+
+```shell
+docker-compose -f g-api/docker-compose.yml up -d
+```
+
+or using the convenience makefile command:
+
+```shell
+make start-backend-docker-guillotina
+```
+
+### Running the acceptance tests with Guillotina backend
+
+If you want to use Guillotina as a backend to run the tests you should run:
+
+```shell
+yarn ci:start-api-plone-guillotina
+```
+
 ## License
 
 MIT License. Copyrights hold the [Plone Foundation](https://plone.org/foundation).

diff --git a/api/versions.cfg b/api/versions.cfg
@@ -48,6 +48,3 @@ sortedcontainers = 2.4.0
 
 # Added by buildout at 2022-02-14 13:57:43.277710
 plone.volto = 4.0.0a3
-
-# Added by buildout at 2022-02-14 13:57:43.277710
-plone.volto = 4.0.0a3
diff --git a/cypress/tests/multilingual/basic-multilingual.js b/cypress/tests/multilingual/basic-multilingual.js
@@ -65,21 +65,48 @@ describe('Basic multilingual Tests', () => {
   });
 
   it('Manage translations menu', function () {
-    cy.navigate('/en');
+    // Create translation
+    cy.get('#toolbar-add').click();
+    cy.findByText('Translate to italiano').click();
+    cy.findByText('Test document');
+    cy.findByText('Traduci in Italiano');
+    cy.get(
+      '.new-translation .documentFirstHeading > .public-DraftStyleDefault-block',
+    ).type('My IT page');
+    cy.get('.new-translation .block.inner.text .public-DraftEditor-content')
+      .type('This is the italian text')
+      .get('span[data-text]')
+      .contains('This is the italian text')
+      .type('{enter}');
+    cy.get('.new-translation .ui.basic.icon.button.block-add-button').click();
+    cy.get('.ui.basic.icon.button.image').contains('Immagine').click();
+    cy.get('#toolbar-save').click();
+    cy.waitForResourceToLoad('@navigation');
+    cy.waitForResourceToLoad('@breadcrumbs');
+    cy.waitForResourceToLoad('@actions');
+    cy.waitForResourceToLoad('@types');
+    cy.waitForResourceToLoad('my-it-page');
+
+    cy.findByLabelText('Vai a english').click();
+
+    // The english doc should be shown
+    cy.get('#page-document').findByText('Test document');
+
     cy.findByLabelText('More').click();
     cy.findByText('Manage Translations').click();
     cy.findByText('Manage translations for');
-    cy.findByText('/en');
-    cy.findByText('/it');
+    cy.findByText('/en/document');
+    cy.findByText('/it/my-it-page');
 
     // Unlink translation for italian
     cy.findByLabelText('Unlink translation for italiano').click();
-    cy.contains('/it').should('not.exist');
+    cy.contains('/it/my-it-page').should('not.exist');
 
     // Link it again
     cy.findByLabelText('Link translation for italiano').click();
     cy.findByLabelText('Back').click();
-    cy.findByLabelText('Select Italiano').dblclick();
-    cy.findByText('/it');
+    cy.findByLabelText('Browse Italiano').click();
+    cy.findByLabelText('Select My IT page').dblclick();
+    cy.findByText('/it/my-it-page');
   });
 });
diff --git a/logos/VoltoLogoEra2-dark-mode.png b/logos/VoltoLogoEra2-dark-mode.png
diff --git a/logos/VoltoLogoEra2.png b/logos/VoltoLogoEra2.png