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