Contribute 🤝

Contribute 🤝#

Plone Recycle Bin is developed as a monorepo containing the Python backend, Volto add-on, documentation, and acceptance tests.

Understand the repository 🏗ī¸#

The monorepo contains these sections:

  • backend contains the plone.recyclebin Python package, Classic UI, REST API, and backend tests.

  • frontend contains the @plone/volto-recyclebin Volto add-on and Cypress tests.

  • docs contains the Sphinx source published to GitHub Pages.

Keeping the packages together provides a complete development environment, lets CI run only for the sections affected by a change, simplifies building the backend and frontend container images, and demonstrates a Plone setup that does not require buildout.

Install prerequisites ✅#

Install the following tools before setting up the repository:

Prepare the development environment 🛠ī¸#

  1. Fork the repository and clone your fork.

    git clone git@github.com:<your-account>/plone-recyclebin.git
cd plone-recyclebin

  2. Install the backend and frontend development environments. This target also creates the initial Plone site on a fresh checkout.

    make install

  3. If the environments are already installed but the site data was removed, create a new Plone site.

    make backend-create-site

  4. Start the backend at http://localhost:8080.

    make backend-start

  5. In another terminal, start the frontend at http://localhost:3000.

    make frontend-start

  6. Open http://localhost:3000 and exercise the change through the UI.

Run the local container stack đŸ“Ļ#

Docker Compose can run backend and frontend images behind Traefik with a PostgreSQL database.

make stack-create-site
make stack-start

Open http://plone-recyclebin.localhost. Use make stack-status to inspect the services and make stack-stop to stop them.

Run checks ✅#

Run all formatters and linters.

make check

To run the stages separately, use these commands.

make format
make lint

The backend uses Ruff for Python formatting and import sorting, Pyroma for package metadata, check-python-versions for Python compatibility, and zpretty for XML and ZCML. See the backend configuration.

The frontend uses ESLint, Prettier, and Stylelint. See the ESLint, Prettier, and Stylelint configuration files. You can also run the corresponding Make targets from the backend or frontend directory.

Run backend and frontend tests.

make test

Build the documentation from the docs directory.

make -C docs html

For changes to delete and restore behavior, also run the Cypress acceptance suite. Start each command in a separate terminal, in this order.

make acceptance-frontend-dev-start

make acceptance-backend-start

make acceptance-test

Update translations 🌐#

Generate the Plone and Volto translation catalogs after changing translatable strings.

make i18n

Submit the change 📨#

  1. Add or update tests that demonstrate the behavior.

  2. Update user, conceptual, or API documentation when behavior changes.

  3. Add a Towncrier news fragment in the appropriate news directory.

  4. Push your branch and open a pull request against main.

Use the issue tracker to report bugs or discuss a change whose behavior or compatibility needs agreement before implementation.

Contents