From 64d0136c1f01e08254ec7cdc8f8e8170b8836f97 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Wed, 1 Jan 2025 22:04:45 -0800 Subject: [PATCH 1/6] Add Standardize project configuration --- docs/developer-guide/index.md | 1 + .../standardize-project-configuration.md | 34 +++++++++++++++++++ 2 files changed, 35 insertions(+) create mode 100644 docs/developer-guide/standardize-project-configuration.md diff --git a/docs/developer-guide/index.md b/docs/developer-guide/index.md index 797edd0d7..f65057d58 100644 --- a/docs/developer-guide/index.md +++ b/docs/developer-guide/index.md @@ -22,4 +22,5 @@ You can help consolidate all of development documentation here, even if it is to :maxdepth: 2 create-a-distribution +standardize-project-configuration ``` diff --git a/docs/developer-guide/standardize-project-configuration.md b/docs/developer-guide/standardize-project-configuration.md new file mode 100644 index 000000000..d2f8bb375 --- /dev/null +++ b/docs/developer-guide/standardize-project-configuration.md @@ -0,0 +1,34 @@ +--- +myst: + html_meta: + "description": "Standardize project configuration in Plone" + "property=og:description": "Standardize project configuration in Plone" + "property=og:title": "Standardize project configuration in Plone" + "keywords": "Plone 6, standardize, project, configuration, development" +--- + +# Standardize project configuration + +This part of the documentation describes how to standardize project configuration in Plone. + +Plone consists of hundreds of projects. +To lessen the effort of configuring a new project in the Plone GitHub organization, and keeping these projects current with latest configuration practices, the Plone community agreed upon a trusted set of configuration items. +The Plone community manages these configuration items using the [`meta`](https://github.com/plone/meta) project. + +You can follow these practices in your own projects, or suggest new or alternative configuration items through the `meta` repository, sharing them with the rest of the Plone community. + + +## `meta` basic usage + +`meta` has a rich set of features. +This section describes the most common use cases. + +Begin by cloning `meta` to any machine, then changing your current working directory into `meta`. + +```shell +git clone https://github.com/plone/meta.git +cd meta +``` + +Now you can run its Python scripts to generate configuration files to manage your project or any project that already uses `meta`. +When you run the script {file}`.py`, it will \ No newline at end of file From ad84220e57382b55c922d38a37e996dfbfbda8d5 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 5 Jan 2025 17:53:08 -0800 Subject: [PATCH 2/6] Add Standardize Python project configuration developer guide - Closes #1827 --- docs/developer-guide/index.md | 2 +- .../standardize-project-configuration.md | 34 ------- ...tandardize-python-project-configuration.md | 99 +++++++++++++++++++ 3 files changed, 100 insertions(+), 35 deletions(-) delete mode 100644 docs/developer-guide/standardize-project-configuration.md create mode 100644 docs/developer-guide/standardize-python-project-configuration.md diff --git a/docs/developer-guide/index.md b/docs/developer-guide/index.md index f65057d58..dfc6d8c50 100644 --- a/docs/developer-guide/index.md +++ b/docs/developer-guide/index.md @@ -22,5 +22,5 @@ You can help consolidate all of development documentation here, even if it is to :maxdepth: 2 create-a-distribution -standardize-project-configuration +standardize-python-project-configuration ``` diff --git a/docs/developer-guide/standardize-project-configuration.md b/docs/developer-guide/standardize-project-configuration.md deleted file mode 100644 index d2f8bb375..000000000 --- a/docs/developer-guide/standardize-project-configuration.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -myst: - html_meta: - "description": "Standardize project configuration in Plone" - "property=og:description": "Standardize project configuration in Plone" - "property=og:title": "Standardize project configuration in Plone" - "keywords": "Plone 6, standardize, project, configuration, development" ---- - -# Standardize project configuration - -This part of the documentation describes how to standardize project configuration in Plone. - -Plone consists of hundreds of projects. -To lessen the effort of configuring a new project in the Plone GitHub organization, and keeping these projects current with latest configuration practices, the Plone community agreed upon a trusted set of configuration items. -The Plone community manages these configuration items using the [`meta`](https://github.com/plone/meta) project. - -You can follow these practices in your own projects, or suggest new or alternative configuration items through the `meta` repository, sharing them with the rest of the Plone community. - - -## `meta` basic usage - -`meta` has a rich set of features. -This section describes the most common use cases. - -Begin by cloning `meta` to any machine, then changing your current working directory into `meta`. - -```shell -git clone https://github.com/plone/meta.git -cd meta -``` - -Now you can run its Python scripts to generate configuration files to manage your project or any project that already uses `meta`. -When you run the script {file}`.py`, it will \ No newline at end of file diff --git a/docs/developer-guide/standardize-python-project-configuration.md b/docs/developer-guide/standardize-python-project-configuration.md new file mode 100644 index 000000000..5d8e34871 --- /dev/null +++ b/docs/developer-guide/standardize-python-project-configuration.md @@ -0,0 +1,99 @@ +--- +myst: + html_meta: + "description": "Standardize project configuration in Plone with meta" + "property=og:description": "Standardize project configuration in Plone with meta" + "property=og:title": "Standardize project configuration in Plone with meta" + "keywords": "Plone 6, standardize, project, configuration, development, meta" +--- + +# Standardize Python project configuration + +This part of the documentation describes how to standardize Python project configuration in Plone. +It does not cover Volto or any other JavaScript-based project, which has its own ecosystem. + +Plone consists of hundreds of projects. +To lessen the effort of configuring a new project in the Plone GitHub organization, and to keep these projects current with latest configuration practices, the Plone community agreed upon a trusted set of configuration items. +The Plone community manages these configuration items using the [`meta`](https://github.com/plone/meta) project. + +You can follow these practices in your own projects, or suggest new or alternative configuration items through the `meta` repository, sharing them with the rest of the Plone community. + + +## `meta` basic usage + +`meta` has a rich set of features. +This section describes the most common use cases. + +```{seealso} +See a description of all of [`meta`'s features](https://github.com/plone/meta/blob/main/config/README.md#quick-start). +``` + + +### Setup + +Clone `meta` to any machine, then change your current working directory into `meta/config`, create a Python virtual environment, activate it, and install `meta`'s requirements. + +```shell +git clone https://github.com/plone/meta.git +cd meta/config +python3 -m venv venv +. venv/bin/activate +pip install -r requirements.txt +``` + + +### `config-package.py` script + +The {file}`config-package.py` Python script from `meta` creates or overwrites configuration files for your project. +See a current list of [configuration files](https://github.com/plone/meta/blob/main/config/README.md#configuration-files) that it will create or overwrite. + +This script has several [command line options](https://github.com/plone/meta/blob/main/config/README.md#cli-arguments) that you can use to override the default options. + +When you run this script, it automatically goes through the following steps. + +1. It creates a new git branch from the current branch in your project. +1. If the file {file}`.meta.toml` is not present in the project, then it creates this and the other new configuration files from `meta`'s Jinja2 templates. + Otherwise, it reads the file {file}`.meta.toml` for regenerating the configuration files. +1. It writes the configuration files. +1. It creates a change log entry. +1. By default, it commits changes. +1. It optionally adds packages, pushes commits, or runs tox from the configuration files. + +```{tip} +If you prefer to name the new git branch instead of letting the script name it using its default naming scheme, then either create a new branch `my-new-branch`, switch to it, and use the `--branch current` option, or do all that in one step with the `--branch my-new-branch` option. +``` + +```{tip} +If you prefer to review changes before committing them, then use the `--no-commit` option. +``` + +For help for the script, use the following command. + +```shell +python config-package.py --help +``` + + +### Generate configuration files + +Now you can run the Python script {file}`config-package.py` to generate configuration files from Jinja2 template files to manage your project. + +```shell +python config-package.py [OPTIONS] PATH/TO/PACKAGE +``` + + +### Manage configuration files + +For each of the configuration files, you should edit its [corresponding stanza](https://github.com/plone/meta/blob/main/config/README.md#applying-a-customized-configuration) in the file {file}`.meta.toml`. + +```{warning} +Do not directly edit the configuration files that `meta` manages. +Anytime someone runs the Python script {file}`config-package.py`, any changes made in these files will get clobbered. +``` + +Then run the Python script {file}`config-package.py` to regenerate configuration files from your project's {file}`.meta.toml`. + +```shell +python config-package.py [OPTIONS] PATH/TO/PACKAGE +``` From 1657f29d4293e4fd4c3420c94013894d6267c25d Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 14 Jan 2025 01:09:50 -0800 Subject: [PATCH 3/6] - s/`meta`/`plone/meta` - add exclusions --- ...tandardize-python-project-configuration.md | 33 +++++++++++-------- 1 file changed, 19 insertions(+), 14 deletions(-) diff --git a/docs/developer-guide/standardize-python-project-configuration.md b/docs/developer-guide/standardize-python-project-configuration.md index 5d8e34871..2a37cbeab 100644 --- a/docs/developer-guide/standardize-python-project-configuration.md +++ b/docs/developer-guide/standardize-python-project-configuration.md @@ -1,37 +1,42 @@ --- myst: html_meta: - "description": "Standardize project configuration in Plone with meta" - "property=og:description": "Standardize project configuration in Plone with meta" - "property=og:title": "Standardize project configuration in Plone with meta" - "keywords": "Plone 6, standardize, project, configuration, development, meta" + "description": "Standardize project configuration in Plone with plone/meta" + "property=og:description": "Standardize project configuration in Plone with plone/meta" + "property=og:title": "Standardize project configuration in Plone with plone/meta" + "keywords": "Plone 6, standardize, project, configuration, development, plone/meta" --- # Standardize Python project configuration This part of the documentation describes how to standardize Python project configuration in Plone. -It does not cover Volto or any other JavaScript-based project, which has its own ecosystem. +It does not cover the following. + +- Volto or any other JavaScript-based project, which has its own ecosystem. +- Monorepos, such as [Cookieplone](https://github.com/plone/cookieplone). + Repositories must have a single Python package at the top level. +- Project that support multiple versions of Plone in the same branch. Plone consists of hundreds of projects. To lessen the effort of configuring a new project in the Plone GitHub organization, and to keep these projects current with latest configuration practices, the Plone community agreed upon a trusted set of configuration items. -The Plone community manages these configuration items using the [`meta`](https://github.com/plone/meta) project. +The Plone community manages these configuration items using the [`plone/meta`](https://github.com/plone/meta) project. -You can follow these practices in your own projects, or suggest new or alternative configuration items through the `meta` repository, sharing them with the rest of the Plone community. +You can follow these practices in your own projects, or suggest new or alternative configuration items through the `plone/meta` repository, sharing them with the rest of the Plone community. -## `meta` basic usage +## `plone/meta` basic usage -`meta` has a rich set of features. +`plone/meta` has a rich set of features. This section describes the most common use cases. ```{seealso} -See a description of all of [`meta`'s features](https://github.com/plone/meta/blob/main/config/README.md#quick-start). +See a description of all of [`plone/meta`'s features](https://github.com/plone/meta/blob/main/config/README.md#quick-start). ``` ### Setup -Clone `meta` to any machine, then change your current working directory into `meta/config`, create a Python virtual environment, activate it, and install `meta`'s requirements. +Clone `plone/meta` to any machine, then change your current working directory into `meta/config`, create a Python virtual environment, activate it, and install `plone/meta`'s requirements. ```shell git clone https://github.com/plone/meta.git @@ -44,7 +49,7 @@ pip install -r requirements.txt ### `config-package.py` script -The {file}`config-package.py` Python script from `meta` creates or overwrites configuration files for your project. +The {file}`config-package.py` Python script from `plone/meta` creates or overwrites configuration files for your project. See a current list of [configuration files](https://github.com/plone/meta/blob/main/config/README.md#configuration-files) that it will create or overwrite. This script has several [command line options](https://github.com/plone/meta/blob/main/config/README.md#cli-arguments) that you can use to override the default options. @@ -52,7 +57,7 @@ This script has several [command line options](https://github.com/plone/meta/blo When you run this script, it automatically goes through the following steps. 1. It creates a new git branch from the current branch in your project. -1. If the file {file}`.meta.toml` is not present in the project, then it creates this and the other new configuration files from `meta`'s Jinja2 templates. +1. If the file {file}`.meta.toml` is not present in the project, then it creates this and the other new configuration files from `plone/meta`'s Jinja2 templates. Otherwise, it reads the file {file}`.meta.toml` for regenerating the configuration files. 1. It writes the configuration files. 1. It creates a change log entry. @@ -88,7 +93,7 @@ python config-package.py [OPTIONS] PATH/TO/PACKAGE For each of the configuration files, you should edit its [corresponding stanza](https://github.com/plone/meta/blob/main/config/README.md#applying-a-customized-configuration) in the file {file}`.meta.toml`. ```{warning} -Do not directly edit the configuration files that `meta` manages. +Do not directly edit the configuration files that `plone/meta` manages. Anytime someone runs the Python script {file}`config-package.py`, any changes made in these files will get clobbered. ``` From 302d6e25d4b015a97dde403c88fe5fcd0b112b8d Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 14 Jan 2025 01:11:50 -0800 Subject: [PATCH 4/6] Remove activate step, adjust commands to include path to binaries --- .../standardize-python-project-configuration.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/docs/developer-guide/standardize-python-project-configuration.md b/docs/developer-guide/standardize-python-project-configuration.md index 2a37cbeab..ca910cfac 100644 --- a/docs/developer-guide/standardize-python-project-configuration.md +++ b/docs/developer-guide/standardize-python-project-configuration.md @@ -36,14 +36,13 @@ See a description of all of [`plone/meta`'s features](https://github.com/plone/m ### Setup -Clone `plone/meta` to any machine, then change your current working directory into `meta/config`, create a Python virtual environment, activate it, and install `plone/meta`'s requirements. +Clone `plone/meta` to any machine, then change your current working directory into `meta/config`, create a Python virtual environment, and install `plone/meta`'s requirements. ```shell git clone https://github.com/plone/meta.git cd meta/config python3 -m venv venv -. venv/bin/activate -pip install -r requirements.txt +venv/bin/pip install -r requirements.txt ``` @@ -75,7 +74,7 @@ If you prefer to review changes before committing them, then use the `--no-commi For help for the script, use the following command. ```shell -python config-package.py --help +venv/bin/python config-package.py --help ``` @@ -84,7 +83,7 @@ python config-package.py --help Now you can run the Python script {file}`config-package.py` to generate configuration files from Jinja2 template files to manage your project. ```shell -python config-package.py [OPTIONS] PATH/TO/PACKAGE +venv/bin/python config-package.py [OPTIONS] PATH/TO/PACKAGE ``` @@ -100,5 +99,5 @@ Anytime someone runs the Python script {file}`config-package.py`, any changes ma Then run the Python script {file}`config-package.py` to regenerate configuration files from your project's {file}`.meta.toml`. ```shell -python config-package.py [OPTIONS] PATH/TO/PACKAGE +venv/bin/python config-package.py [OPTIONS] PATH/TO/PACKAGE ``` From a27eaa2c5c0abff8f0d7bf3f5ed15ef9093fd43f Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 14 Jan 2025 11:17:43 -0800 Subject: [PATCH 5/6] Reword monorepo definition --- .../developer-guide/standardize-python-project-configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/developer-guide/standardize-python-project-configuration.md b/docs/developer-guide/standardize-python-project-configuration.md index ca910cfac..8c08903ed 100644 --- a/docs/developer-guide/standardize-python-project-configuration.md +++ b/docs/developer-guide/standardize-python-project-configuration.md @@ -13,7 +13,7 @@ This part of the documentation describes how to standardize Python project confi It does not cover the following. - Volto or any other JavaScript-based project, which has its own ecosystem. -- Monorepos, such as [Cookieplone](https://github.com/plone/cookieplone). +- Monorepo projects with backend and frontend code bases, such as those created by [Cookieplone](https://github.com/plone/cookieplone). Repositories must have a single Python package at the top level. - Project that support multiple versions of Plone in the same branch. From 3fe5f57ea08233e1ee67c8aa2453a631d7e9698a Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 14 Jan 2025 11:19:22 -0800 Subject: [PATCH 6/6] Update docs/developer-guide/standardize-python-project-configuration.md Co-authored-by: Maurits van Rees --- .../developer-guide/standardize-python-project-configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/developer-guide/standardize-python-project-configuration.md b/docs/developer-guide/standardize-python-project-configuration.md index 8c08903ed..77930b074 100644 --- a/docs/developer-guide/standardize-python-project-configuration.md +++ b/docs/developer-guide/standardize-python-project-configuration.md @@ -15,7 +15,7 @@ It does not cover the following. - Volto or any other JavaScript-based project, which has its own ecosystem. - Monorepo projects with backend and frontend code bases, such as those created by [Cookieplone](https://github.com/plone/cookieplone). Repositories must have a single Python package at the top level. -- Project that support multiple versions of Plone in the same branch. +- Projects that support multiple versions of Plone in the same branch. Plone consists of hundreds of projects. To lessen the effort of configuring a new project in the Plone GitHub organization, and to keep these projects current with latest configuration practices, the Plone community agreed upon a trusted set of configuration items.