From 2b9dcfa30ea692c2dbbde203cf995c0523d3c2c7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Katja=20Su=CC=88ss?= Date: Tue, 8 Apr 2025 12:44:07 +0200 Subject: [PATCH 1/9] contributing: skip buildout, use magic --- docs/contributing/core/index.md | 48 +++++++-------------------------- 1 file changed, 9 insertions(+), 39 deletions(-) diff --git a/docs/contributing/core/index.md b/docs/contributing/core/index.md index 968395052..415e9cdd7 100644 --- a/docs/contributing/core/index.md +++ b/docs/contributing/core/index.md @@ -79,61 +79,31 @@ On Linux, [GNU Compiler Collection (GCC)](https://gcc.gnu.org/) is a common opti 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. +Former 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. ```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. +If you want to contribute to another Plone version but the current one, switch the branch. -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`. +Install Plone and run it: ```shell -#/bin/sh -`which python3.11` -m venv . +make run ``` -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. +See more make options with `make help`. -```shell -./bin/instance fg -``` - -```{include} /_inc/_create-classic-ui-instance.md -``` - -```{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`. -``` +If you prefer buildout, skip to former docs. +See options on the bottom left of docs.plone.org. (contributing-core-work-with-git-label)= From abc5d5ff0da7548516b0461db8b1d0f2681d0ffd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Katja=20Su=CC=88ss?= Date: Fri, 18 Apr 2025 15:18:04 +0200 Subject: [PATCH 2/9] Simplify instructions on "## Install Plone core for development". Be more polite to new contributors. --- docs/contributing/core/index.md | 20 +++++++------------- 1 file changed, 7 insertions(+), 13 deletions(-) diff --git a/docs/contributing/core/index.md b/docs/contributing/core/index.md index 415e9cdd7..ce1fbb2ab 100644 --- a/docs/contributing/core/index.md +++ b/docs/contributing/core/index.md @@ -12,16 +12,15 @@ 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. +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. ```{important} -You must {ref}`contributing-sign-and-return-the-plone-contributor-agreement-label` before your contribution can be accepted. +Please {ref}`contributing-sign-and-return-the-plone-contributor-agreement-label` before you contribute. +This is not optional, but a must before your contribution can be accepted. ``` @@ -73,7 +72,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`. @@ -83,27 +82,22 @@ Former 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 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. +To set up a Plone 6 development environment, clone https://github.com/plone/buildout.coredev. ```shell git clone https://github.com/plone/buildout.coredev cd buildout.coredev ``` -If you want to contribute to another Plone version but the current one, switch the branch. - Install Plone and run it: ```shell make run ``` -See more make options with `make help`. - -If you prefer buildout, skip to former docs. -See options on the bottom left of docs.plone.org. +See more `make` options/targets in the README of the buildout.coredev repo. (contributing-core-work-with-git-label)= From 2a7552bad7d70fbe830fc3415a135968191a5142 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Katja=20Su=CC=88ss?= Date: Fri, 18 Apr 2025 15:30:04 +0200 Subject: [PATCH 3/9] myST fix --- docs/contributing/core/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing/core/index.md b/docs/contributing/core/index.md index ce1fbb2ab..ebd8186a2 100644 --- a/docs/contributing/core/index.md +++ b/docs/contributing/core/index.md @@ -97,7 +97,7 @@ Install Plone and run it: make run ``` -See more `make` options/targets in the README of the buildout.coredev repo. +See more `make` options/targets in the READMEs of the `buildout.coredev` repo. (contributing-core-work-with-git-label)= From d485e1b7ee4d5f94ec04addfdd39e544fd6b0ea7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Katja=20Su=CC=88ss?= Date: Thu, 15 May 2025 07:47:30 +0200 Subject: [PATCH 4/9] Back to former punctuation --- docs/contributing/core/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing/core/index.md b/docs/contributing/core/index.md index ebd8186a2..3b7ed01d3 100644 --- a/docs/contributing/core/index.md +++ b/docs/contributing/core/index.md @@ -12,7 +12,7 @@ myst: This guide describes the process of how to contribute to, and develop in, Plone core. It expands upon {doc}`/contributing/index`. -Although Plone core includes Volto — the React based, default frontend for Plone 6 — this guide does not apply to Volto and its packages. +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. From 2cb0a1e56c2196838c04ab54251179d7d4c97b08 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Katja=20Su=CC=88ss?= Date: Thu, 15 May 2025 07:49:13 +0200 Subject: [PATCH 5/9] less like before --- docs/contributing/core/index.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/contributing/core/index.md b/docs/contributing/core/index.md index 3b7ed01d3..aad27e674 100644 --- a/docs/contributing/core/index.md +++ b/docs/contributing/core/index.md @@ -19,8 +19,7 @@ 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} -Please {ref}`contributing-sign-and-return-the-plone-contributor-agreement-label` before you contribute. -This is not optional, but a must before your contribution can be accepted. +You must {ref}`contributing-sign-and-return-the-plone-contributor-agreement-label` before your contribution can be accepted. ``` From 446745688e385d80d17225f83d36fc0e71da645d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Katja=20Su=CC=88ss?= Date: Thu, 15 May 2025 07:50:30 +0200 Subject: [PATCH 6/9] Older versions not former versions --- docs/contributing/core/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing/core/index.md b/docs/contributing/core/index.md index aad27e674..d3867f98c 100644 --- a/docs/contributing/core/index.md +++ b/docs/contributing/core/index.md @@ -77,7 +77,7 @@ On Linux, [GNU Compiler Collection (GCC)](https://gcc.gnu.org/) is a common opti The tool that installs Plone core is `buildout.coredev`. The current default and development branch of `buildout.coredev` is `6.1` -Former versions are named according to their `major.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. From 3671d5341706d0ed7400bbd0786f6eaa0c6dc3e0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Katja=20Su=CC=88ss?= Date: Thu, 15 May 2025 07:54:13 +0200 Subject: [PATCH 7/9] "git" now capitalized --- docs/contributing/core/index.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/contributing/core/index.md b/docs/contributing/core/index.md index d3867f98c..6bf034b1d 100644 --- a/docs/contributing/core/index.md +++ b/docs/contributing/core/index.md @@ -15,8 +15,8 @@ It expands upon {doc}`/contributing/index`. 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. @@ -81,7 +81,7 @@ 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, 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, clone https://github.com/plone/buildout.coredev. @@ -101,7 +101,7 @@ See more `make` options/targets in the READMEs of the `buildout.coredev` repo. (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. @@ -109,7 +109,7 @@ This section applies to members of the GitHub `plone/developers` team, who have 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`. @@ -164,7 +164,7 @@ For more information, see {doc}`mrdeveloper`. ``` ````{tip} -To avoid conflicts with `buildout.coredev` files, you can configure git for your user. +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. From 007029f9260ba283a2c36dc243afdbcaf2ef1428 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Katja=20Su=CC=88ss?= Date: Thu, 15 May 2025 08:02:32 +0200 Subject: [PATCH 8/9] Add link to the README concerning make options/targets --- docs/contributing/core/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing/core/index.md b/docs/contributing/core/index.md index 6bf034b1d..5c6499e14 100644 --- a/docs/contributing/core/index.md +++ b/docs/contributing/core/index.md @@ -96,7 +96,7 @@ Install Plone and run it: make run ``` -See more `make` options/targets in the READMEs of the `buildout.coredev` repo. +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)= From 8823815465e3a7188422a685d09efba73e585763 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Katja=20Su=CC=88ss?= Date: Thu, 15 May 2025 10:12:48 +0200 Subject: [PATCH 9/9] ## Edit packages and ## Test locally --- docs/contributing/core/index.md | 84 +++++++++------------------------ 1 file changed, 23 insertions(+), 61 deletions(-) diff --git a/docs/contributing/core/index.md b/docs/contributing/core/index.md index 5c6499e14..a2ad10818 100644 --- a/docs/contributing/core/index.md +++ b/docs/contributing/core/index.md @@ -136,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`. -``` - -````{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 +make sources-dirty +make run ``` -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. @@ -190,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 ```