Contribute to Plone 6 core#

This guide describes the process of how to contribute to, and develop in, Plone core. It expands upon Contributing to Plone.

Important

Although Plone core includes Volto—the React based, default frontend for Plone 6—this guide does not apply to Volto and its packages. To contribute to Volto, see Contributing to Volto.

This guide assumes that you have basic knowledge of how to use git and GitHub. If you have never contributed to Plone, or you lack basic knowledge of how to use git and GitHub, you should first read First-time contributors for more information.

Important

You must Sign and return the Plone Contributor Agreement before your contribution can be accepted.

Version support policy#

Before you contribute to Plone core, check the version support policy to see which versions of Plone are currently supported.

Prerequisites#

It is beyond the scope of this documentation to provide installation instructions for all prerequisites for your operating system. However, the following links and sections below may be helpful.

  • An operating system that runs all the requirements mentioned. Most UNIX-based operating systems are supported, including many Linux distributions, macOS, or Windows Subsystem for Linux (WSL) on Windows. A UNIX-based operating system is recommended.

    Important

    Windows alone is not recommended because it does not support GNU make. If you get Plone to run on Windows alone, please feel free to document and share your process.

  • Python 3.8, 3.9, 3.10, 3.11, or 3.12

  • GNU make

  • Git

  • A C compiler

Python#

Installing Python is beyond the scope of this documentation. However, it is recommended to use a Python version manager, pyenv that allows you to install multiple versions of Python on your development environment without destroying your system's Python. Plone requires Python version 3.8, 3.9, 3.10, 3.11, or 3.12.

Make#

Make comes installed on most Linux distributions. On macOS, you must first install Xcode, then install its command line tools. On Windows, it is strongly recommended to Install Linux on Windows with WSL, which will include make.

Finally, it is a good idea to update your system's version of make, because some distributions, especially macOS, have an outdated version. Use your favorite search engine or trusted online resource for how to update make.

Git#

Install git for your operating system.

C compiler#

You need a C compiler on your system to compile some of the Python libraries that Plone uses.

On macOS, Developer Tools provides Clang for a C compiler.

On Linux, GNU Compiler Collection (GCC) is a common option.

Install Plone core for development#

The tool that installs Plone core is buildout.coredev.

The current default and development branch of buildout.coredev is 6.1 Older versions are named according to their major.minor version. Its versions align with Plone's major.minor versions.

Use a separate directory for each version of Plone to which you want to contribute. This will avoid switching between git branches, then re-running buildout, which can cause dependency conflicts between versions of Plone.

To set up a Plone 6 development environment, change your working directory to wherever you place your projects, and clone https://github.com/plone/buildout.coredev. You can specify the branch that you want to check out with the -b option.

cd [MY_PROJECTS]
# clone a specific major.minor version branch
git clone -b 6.1 https://github.com/plone/buildout.coredev
cd buildout.coredev

Important

If you want to use a Python version that is not 3.11, follow these instructions.

Open the file bootstrap.sh at the root of the repository. Notice that the script expects Python 3.11 to be installed on your system and in your user's PATH.

#/bin/sh
`which python3.11` -m venv .

Edit it according to the Python version you want to use, then save and close the file. After you have run the script, you should undo the change, otherwise you have a local change in git that you might accidentally commit.

Now run the script to install Plone 6.

./bootstrap.sh

This will run for a long time if it's your first pull (approximately 10-20 minutes, depending on network speed and your hardware).

Once that's done, you can start an instance of Plone with the following command.

./bin/instance fg

To visit your Plone instance, you can open the link http://0.0.0.0:8080 in a web browser.

You will be presented with several options. Click the button Create Classic UI Plone site.

Enter values in the form, and click the button Create Plone Site.

You will be redirected to your new Classic UI Plone site.

Warning

Ignore the warning about accessing the Plone backend through its Classic UI frontend.

Do not follow the instructions to install Volto. They will not work with buildout. To contribute to Volto, you will need to start over, and follow Contributing to Volto.

To login, the default credentials are the following.

  • username: admin

  • password: admin

Work with git#

Important

This section applies to members of the GitHub plone/developers team, who have write access to repositories under the Plone GitHub organization.

Members of the plone/contributors team do not have write access, and instead must follow the process to set up their remote upstream and origin branches as described in Set up your environment.

Always begin by checking out the git branch on which you want to work. This is the base branch to which you will create a pull request.

If you just cloned https://github.com/plone/buildout.coredev, then the 6.1 branch is checked out and current, and you can skip the rest of this section and continue on the next, Edit packages.

git checkout 6.1

Next pull down and merge any recent changes from the remote tracked repository with a single command.

git pull

Edit packages#

First identify the names of the Plone packages you want to work on. If you do not know, you can ask in the Plone Community Forum. Only a few packages are in src/ by default.

Next create a new file buildout.local.cfg, and add the names of packages that you want to develop under the auto-checkout list.

[buildout]
extends =
  buildout.cfg

auto-checkout =
    # Add packages that you want to develop
    plone.app.event
    icalendar
    # others
    ...

When you make changes in your package, then rerun buildout with the following command, specifying your new buildout configuration file with the -c option. You can add the -N flag to save time by not checking PyPI to see if there are updates to packages that were already installed.

./bin/buildout -c buildout.local.cfg -N

See also

mr.developer checks out additional repositories using the auto-checkout option. For more information, see mr.developer.

Tip

To avoid conflicts with buildout.coredev files, you can configure git for your user. Either create or edit a file at ~/.gitconfig. Then add the following stanza to it.

[core]
    excludesfile = ~/.gitignore_global

Then add any standard .gitignore syntax to exclude files from getting committed and pushed to a remote repository.

Next create a new development branch on which you want to work from the current branch, tracking the upstream Plone repository, and check it out. It's a good idea to use a branch name that includes the issue number and is descriptive of what it resolves.

git switch -c 123-thing-i-fixed

Now you can edit your code without affecting the original branch.

Test locally#

If you change the expected behavior of a feature in a package, you should write a test to cover the change.

To run a test for the specific package that you modified, use the -s option followed by the package name, as shown in the following example.

./bin/test -s plone.app.event

If any test fails, do not commit and push the changes. Instead write a test that passes.

After the package level tests pass with your change, you can Create a pull request and let CI run and ask Jenkins to run the full test suite.

However, if CI or Jenkins report a test failure that you want to troubleshoot locally, you can run the full unit test suite to ensure other packages aren't affected by the change. It takes 5-10 minutes to run the full unit test suite.

# Run unit tests
./bin/test

If you run acceptance tests with the --all option, it will run tests in a real browser. This takes 30-40 minutes to run. This may repeatedly launch and close browser windows that gain focus, disrupting you from doing any other work. If this happens, you can install the chromedriver OS package. See https://developer.chrome.com/docs/chromedriver. Then run export ROBOT_BROWSER="headlesschrome" and again run bin/test --all.

# Run acceptance tests
./bin/test --all

Change log#

All changes require a change log entry.

For packages that use towncrier to produce change logs, see Change log entry. A package that uses towncrier has a news directory at its repository or package root.

For packages that don't use towncrier, edit either CHANGES.rst, CHANGES.txt, or HISTORY.txt in each package you have modified, adding a summary of the change. New change log entries should be added at the top of CHANGES.rst.

Create a pull request#

After you have completed all the foregoing steps, push your changes to a remote branch and create a pull request in GitHub. If you are working from an issue, include "Fixes #ISSUE-NUMBER" in the description. This enables automatic closing of the related issue when the pull request is merged. This also creates a hyperlink to the original issue for easy reference.

Continuous integration#

Plone project repositories use continuous integration (CI) to run tests, ensure code quality, or provide previews for every contribution. Plone uses GitHub workflows, Jenkins, Cypress, Read the Docs, and other services for CI. All of a project's CI jobs must pass before a contribution may be accepted.

See also

Continuous integration