Skip to content

Contributing to Plone core: skip buildout, use magic #1936

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 18 commits into from
Jun 11, 2025
Merged

Contributing to Plone core: skip buildout, use magic #1936

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
2b9dcfa
contributing: skip buildout, use magic
ksuess Apr 8, 2025
abc5d5f
Simplify instructions on "## Install Plone core for development". Be …
ksuess Apr 18, 2025
2a7552b
myST fix
ksuess Apr 18, 2025
d485e1b
Back to former punctuation
ksuess May 15, 2025
2cb0a1e
less like before
ksuess May 15, 2025
4467456
Older versions not former versions
ksuess May 15, 2025
3671d53
"git" now capitalized
ksuess May 15, 2025
007029f
Add link to the README concerning make options/targets
ksuess May 15, 2025
8823815
## Edit packages and ## Test locally
ksuess May 15, 2025
a5f37f4
Merge branch '6.0' into instructions-for-setup-to-contribute-to-core-…
stevepiercy Jun 1, 2025
aa05554
Apply suggestions from code review
ksuess Jun 2, 2025
8e42c91
Apply suggestions from code review
ksuess Jun 2, 2025
040ef63
6.1 -> {PLONE_BACKEND_MINOR_VERSION}
ksuess Jun 2, 2025
24ee6e2
Apply suggestions from code review
ksuess Jun 3, 2025
fa41bda
Merge branch '6.0' into instructions-for-setup-to-contribute-to-core-…
stevepiercy Jun 5, 2025
652da03
Choose a distribution depending on whether you are developing for Cla…
ksuess Jun 10, 2025
953bd44
Merge branch '6.0' into instructions-for-setup-to-contribute-to-core-…
ksuess Jun 10, 2025
4feba2b
Update docs/contributing/core/index.md
stevepiercy Jun 11, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
153 changes: 44 additions & 109 deletions docs/contributing/core/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,13 +12,11 @@ myst:
This guide describes the process of how to contribute to, and develop in, Plone core.
It expands upon {doc}`/contributing/index`.

```{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 {doc}`../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 {doc}`/contributing/first-time` for more information.
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 {doc}`/contributing/first-time` for more information.

```{important}
You must {ref}`contributing-sign-and-return-the-plone-contributor-agreement-label` before your contribution can be accepted.
Expand Down Expand Up @@ -73,86 +71,58 @@ On macOS, Developer Tools provides Clang for a C compiler.
On Linux, [GNU Compiler Collection (GCC)](https://gcc.gnu.org/) is a common option.



(contributing-core)=
## 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`
The current default and development branch of `buildout.coredev` is `{PLONE_BACKEND_MINOR_VERSION}`.
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.
This will avoid switching between Git branches, 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.
To set up a Plone 6 development environment, clone https://github.com/plone/buildout.coredev.

```shell
cd [MY_PROJECTS]
# clone a specific major.minor version branch
git clone -b 6.1 https://github.com/plone/buildout.coredev
git clone 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 {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`.

```shell
#/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.

```shell
./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.
Use the following command to install Plone and run it.

```shell
./bin/instance fg
make run
```

```{include} /_inc/_create-classic-ui-instance.md
```
To create and visit a new Plone site, visit http://localhost:8080, select the Classic UI distribution, and fill out and submit the form, ensuring you create a site with sample content against which you can test.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why Classic UI specifically? I often install the Volto distribution if I'm working on backend changes that I want to test with Volto.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, of course, this should not recommend one of the distributions.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@ksuess @davisagli the instructions on this page do not cover starting the Volto frontend and don't include how to start to develop in Volto. In fact, the second sentence of this page states the following.

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.

Unless and until the instructions on this page actually support Volto development, then we should use the previous version of this sentence, telling developers to select Classic UI.

In my testing, I couldn't even visit the Volto frontend because it doesn't get started. Maybe there is a way to do that, and if there is, then let's get it into this page.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@stevepiercy When I'm working on something that involves changes in both Volto and in the backend, I start Volto from the volto repository (as covered in https://plone6--1936.org.readthedocs.build/volto/contributing/developing-core.html#start-plone) and then I start the backend from the buildout.coredev repository (instead of running make backend-docker-start from the volto repository, which doesn't give the option to check out backend packages) and then create a site using the Volto distribution.

I'm totally okay with leaving that as out of scope for this PR (let's get this merged), but I think we should explain it somewhere (maybe it belongs under "Contributing to Volto", but it's really about contributing to the backend and then testing those changes with Volto before they're released)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(Maybe we should add a make frontend-docker-start command to buildout.coredev to parallel make backend-docker-start in the Volto repository, in case you just want to get the most recent Volto release running quickly for testing without cloning it separately)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@stevepiercy When I'm working on something that involves changes in both Volto and in the backend, I start Volto from the volto repository (as covered in https://plone6--1936.org.readthedocs.build/volto/contributing/developing-core.html#start-plone) and then I start the backend from the buildout.coredev repository (instead of running make backend-docker-start from the volto repository, which doesn't give the option to check out backend packages) and then create a site using the Volto distribution.

Are you saying that you have two clones, one each for volto and buildout.coredev as siblings or something?

I'm totally okay with leaving that as out of scope for this PR (let's get this merged),

Yeah, I think it is out of scope here.

but I think we should explain it somewhere (maybe it belongs under "Contributing to Volto", but it's really about contributing to the backend and then testing those changes with Volto before they're released)

Are you saying, for example, adding or editing a plone.restapi endpoint in your buildout.coredev checkout, then running tests in your volto checkout? If so, we don't have that in the docs yet. It never occurred to me to have the two checkouts talk to each other. I guess as long as the backend runs on the same host and port that the volto checkout requires, it's all good, right?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@stevepiercy Yeah, that's right, there's no actual configuration to make the two repositories work with each other, it's just based on the convention of running the backend on port 8080, and Volto expecting one there by default.


```{warning}
Ignore the warning about accessing the Plone backend through its Classic UI frontend.
Stop Plone with the keyboard shortcut {kbd}`ctrl-c`.

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 {doc}`../volto`.
```{seealso}
For more Make targets, see documentation in [`buildout.coredev`'s `README-make.md` file](https://github.com/plone/buildout.coredev/blob/{PLONE_BACKEND_MINOR_VERSION}/README-make.md).
The most relevant section is [How to use the `Makefile`](https://github.com/plone/buildout.coredev/blob/{PLONE_BACKEND_MINOR_VERSION}/README-make.md#how-to-use-the-makefile).
```


(contributing-core-work-with-git-label)=

## Work with git
## 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 {ref}`set-up-your-environment-label`.
```

Always begin by checking out the git branch on which you want to work.
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, {ref}`contributing-core-edit-packages-label`.
If you just cloned `https://github.com/plone/buildout.coredev`, then the `{PLONE_BACKEND_MINOR_VERSION}` branch is checked out and current, and you can skip the rest of this section and continue on the next, {ref}`contributing-core-edit-packages-label`.

```shell
git checkout 6.1
git checkout {PLONE_BACKEND_MINOR_VERSION}
```

Next pull down and merge any recent changes from the remote tracked repository with a single command.
Expand All @@ -173,46 +143,21 @@ You can also ask in the [Plone Community Forum](https://community.plone.org/).

Only a few packages are in {file}`src/` by default.

Next create a new file {file}`buildout.local.cfg`, and add the names of packages that you want to develop under the `auto-checkout` list.
Next, edit the file {file}`mxcheckouts.ini` at the root of your checkout, adding the name of the package that you want to develop as a new section.
The following example adds `plone.app.multilingual`.

```ini
[buildout]
extends =
buildout.cfg

auto-checkout =
# Add packages that you want to develop
plone.app.event
icalendar
# others
...
[plone.app.multilingual]
use = true
```

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.
You can now check out the package and start your instance with the checked out package using the following commands.

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

```{seealso}
`mr.developer` checks out additional repositories using the `auto-checkout` option.
For more information, see {doc}`mrdeveloper`.
make sources-dirty
make run
```

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

```cfg
[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.

Expand All @@ -227,54 +172,44 @@ 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.
If you change the expected behavior of a feature in a package, you should write a unit or acceptance test, as appropriate, 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.
Plone uses [Playwright](https://playwright.dev/) to run acceptance tests.
`plone.app.robotframework` provides a script to install Playwright browsers.

```shell
./bin/test -s plone.app.event
.venv/bin/rfbrowser init
```

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 {ref}`contributing-core-create-a-pull-request-label` 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.
To run tests for the specific package that you modified, use `.venv/bin/pytest` followed by the package name, as shown in the following example.

```shell
# Run unit tests
./bin/test
.venv/bin/pytest src/plone.app.multilingual
```

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 use `headlesschrome` as the test browser.
First set an environment variable.

```shell
export ROBOT_BROWSER="headlesschrome"
```
If any test fails, do not commit and push the changes.
Instead write a test that passes.

Then run all tests again.
Following [How to invoke pytest](https://docs.pytest.org/en/stable/how-to/usage.html), you can run tests for the package you're developing.
Using the pytest keyword option `-k`, followed by a string expression in double quotes, you can select only unit tests or only acceptance tests to run as shown below.
With no options, pytest will run all tests.

```shell
bin/test --all
.venv/bin/pytest src/plone.app.multilingual -v -k "not robot"
```

Plone uses [Playwright](https://playwright.dev/) to run robot tests.
`plone.app.robotframework` provides a script to install Playwright browsers.

```shell
./bin/rfbrowser init
.venv/bin/pytest src/plone.app.multilingual -v -k "robot"
```

After the script downloads and initalizes browser resources, you can run the acceptance tests.
After the package level tests pass with your change, you can {ref}`contributing-core-create-a-pull-request-label`, which will start the CI checks.
After all CI checks pass, then you can ask Jenkins to run the full test suite.

If either CI or Jenkins report a test failure, and you want to troubleshoot it locally, then you can run the full test suite to ensure other packages aren't affected by the change.
It takes about 15-20 minutes to run the full unit test suite.

```shell
./bin/test --all
.venv/bin/pytest
```


Expand Down
2 changes: 1 addition & 1 deletion docs/contributing/core/release.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,7 @@ These are:
```shell
git clone [email protected]:plone/buildout.coredev.git
cd buildout.coredev
git checkout 6.1
git checkout {PLONE_BACKEND_MINOR_VERSION}
./bootstrap.sh
bin/buildout -c buildout.cfg
```
Expand Down