# plone.meta

> Standardize configuration files across Plone-related Python repositories.

plone.meta generates and manages a consistent set of configuration files for Plone
Python packages: .editorconfig, .flake8, .gitignore, pyproject.toml, tox.ini,
.pre-commit-config.yaml, and CI pipelines (GitHub Actions, GitLab CI).

## Key Facts

- Package: plone.meta
- Version: 2.4.1.dev0
- License: GPLv2
- Python: 3.9+, with support up to Python 3.14
- Repository: https://github.com/plone/meta
- PyPI: https://pypi.org/project/plone.meta/
- Install: pip install plone.meta

## Commands

### config-package

The main command. Generates configuration files for a target Python package
repository from Jinja2 templates. Reads per-repository customizations from
.meta.toml. Creates a git branch, commits changes, and optionally pushes.

Usage: config-package [OPTIONS] PATH

Options:
  --branch BRANCH_NAME  Git branch name (use "current" for current branch)
  --commit-msg MSG      Custom commit message
  --no-commit           Don't commit changes
  --push                Push changes
  --tox                 Run tox after configuration
  --track               Add package to packages.txt
  -t, --type TYPE       Configuration type (default: "default")

### multi-call

Runs config-package across multiple repositories listed in a packages.txt file.

Usage: multi-call SCRIPT PACKAGES_FILE CLONES_DIR [ARGS...]

### switch-to-pep420

Converts packages from pkg_resources-style namespace packages to PEP 420
native namespace packages.

Usage: switch-to-pep420 [OPTIONS] PATH

### re-enable-actions

Re-enables GitHub Actions on repositories where they were auto-disabled.

Usage: re-enable-actions

## Generated Files

- .meta.toml: plone.meta's configuration (the only file you should edit)
- .editorconfig: Editor settings
- .flake8: Flake8 linting rules
- .gitignore: Git ignore patterns
- .github/workflows/meta.yml: GitHub Actions CI (GitHub repos only); default jobs: qa, coverage, dependencies, release_ready, circular (note: "test" no longer included by default)
- .github/workflows/test-matrix.yml: GitHub Actions test matrix workflow (GitHub repos only); generated when use_test_matrix is true (default)
- .gitlab-ci.yml: GitLab CI (GitLab repos only)
- .pre-commit-config.yaml: Pre-commit hooks
- pyproject.toml: Python tooling configuration
- tox.ini: Test environment definitions (uses modular sub-templates: tox-init.j2, tox-base.j2, tox-test-runner-specifics.j2, tox-test-coverage.j2, tox-qa.j2, tox-plone-depending-qa.j2)

## Test Matrix

A major feature of plone.meta 2.x. Tests all combinations of Plone versions
and Python versions. Default matrix:
- Plone 6.2: Python 3.14, 3.13, 3.12, 3.11, 3.10
- Plone 6.1: Python 3.13, 3.12, 3.11, 3.10
- Plone 6.0: Python 3.13, 3.12, 3.11, 3.10

Generated tox environments follow the pattern: py314-plone62, py313-plone61, etc.

Configurable via [tox] test_matrix and [tox] use_test_matrix in .meta.toml.

## .meta.toml Configuration

All customization goes into .meta.toml. Never edit generated files directly.

Sections: [meta], [editorconfig], [flake8], [gitignore], [github], [gitlab],
[pre_commit], [pyproject], [tox]

Most sections support extra_lines for appending custom configuration.

### Key 2.x changes

- [github] jobs: default no longer includes "test" (replaced by test-matrix.yml)
- [github] extra_lines_after_os_dependencies: replaces py_versions
- [gitlab] custom_images: dict keyed by Python version (replaces custom_image string)
- [tox] constraints_files: dict keyed by Plone version (replaces constraints_file string)
- [tox] test_matrix: dict defining Plone version to Python versions mapping
- [tox] use_test_matrix: boolean (default true) to enable/disable test matrix
- [tox] skip_test_extra: boolean for packages without a test extra

## Shared Workflows & Actions

plone/meta provides reusable GitHub Actions workflows and composite actions
for Cookieplone-based projects (not used by config-package):

Composite actions: setup_backend_uv, setup_frontend, setup_uv
Backend workflows: backend-lint, backend-pytest, backend-pytest-coverage
Documentation workflows: docs-build
Frontend workflows: frontend-acceptance, frontend-code, frontend-i18n, frontend-storybook, frontend-unit
Container workflows: container-image-build-push, container-image-build, container-image-push

## tox Environments

- test: Run the test suite (with test matrix: py314-plone62, py313-plone61, etc.)
- coverage: Test coverage reporting
- lint: Code quality checks via pre-commit
- format: Auto-formatting (isort, black, zpretty)
- release-check: Release readiness validation
- dependencies: Dependency declaration check
- circular: Circular dependency detection
- dependencies-graph: Visual dependency graph

## Documentation Sections

- Tutorials: Getting started, bulk updates
- How-To Guides: Install, customize .meta.toml, configure CI, re-enable actions
- Reference: CLI options, .meta.toml options, generated files, tox environments, shared workflows, changelog
- Explanation: Why standardize, architecture, configuration philosophy, scope
