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

Open
wants to merge 9 commits into
base: 6.0
Choose a base branch
from
Open

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

Changes from all commits
Commits
Show all changes
9 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
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
143 changes: 34 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,7 +71,7 @@ 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`.
Expand All @@ -83,70 +81,35 @@ 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.
Install Plone and run it:

```shell
./bin/instance fg
```

```{include} /_inc/_create-classic-ui-instance.md
make run
```

```{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 {doc}`../volto`.
```
See more `make` options/targets in the READMEs of the `buildout.coredev` repo: https://github.com/plone/buildout.coredev/blob/6.1/README-make.md


(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`.
Expand All @@ -173,46 +136,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 file {file}`mxcheckouts.ini`, and add the name of the package that you want to develop.
For example `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:

```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 +165,41 @@ 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 and/or acceptance 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.
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.
You can run all tests for the package you are developing or just unit tests or just acceptance 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` 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 test suite to ensure other packages aren't affected by the change.
It takes a while to run the full unit test suite.

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


Expand Down