Configure Your First Package

Configure Your First Package#

Run config-package on a Plone repository, inspect the generated files, and customize via .meta.toml. This workflow is especially useful for collective repositories adopting standard Plone tooling.

Prerequisites#

  • Python 3.10 or later (with uv recommended)

  • Git

  • A Plone Python package repository to configure (or you can use any single-package Python repository)

Run config-package#

Pick a target repository. For this example, use plone.api:

git clone https://github.com/plone/plone.api.git

Run config-package using uvx:

uvx --from=plone.meta config-package plone.api

Note

If you prefer a local installation instead of uvx, see Install plone.meta for the virtual environment approach, then run .venv/bin/config-package plone.api.

The output shows:

  1. A new git branch (named config-with-default-template-<hash>)

  2. Configuration files written

  3. A commit created

Inspect the results#

Look at the generated files:

cd plone.api
git log --oneline -1
git diff HEAD~1 --stat

config-package created or updated these files:

  • .meta.toml – plone.meta’s own configuration

  • .editorconfig – editor settings

  • .flake8 – flake8 linting rules

  • .gitignore – git ignore patterns

  • .github/workflows/meta.yml – GitHub Actions CI (for GitHub-hosted repos)

  • .pre-commit-config.yaml – pre-commit hooks

  • pyproject.toml – Python tooling configuration

  • tox.ini – tox test environments

Understand .meta.toml#

Open .meta.toml, the central configuration file:

[meta]
template = "default"
commit-id = "a1b2c3d4"

[tox]
test_runner = "zope.testrunner"

All your customizations go into .meta.toml. Re-running config-package reads this file and regenerates everything else.

Important

Do not edit generated files directly. They are overwritten each time config-package runs. All customization goes into .meta.toml.

Try a customization#

Add extra lines to the .flake8 configuration by editing .meta.toml:

[flake8]
extra_lines = """
per-file-ignores =
    setup.py:T20
"""

Re-run config-package on the current branch:

uvx --from=plone.meta config-package --branch current .

Check .flake8 – your custom lines appear below the standard configuration.

Run the generated tox environments#

The generated tox.ini provides several environments:

# Run the test suite
tox -e test

# Check code formatting
tox -e lint

# Check if the package is release-ready
tox -e release-check

Summary#

You now know how to:

  • Run config-package on a repository

  • Inspect the generated files

  • Customize behaviour through .meta.toml

  • Re-run config-package after configuration changes

  • Use the generated tox environments

Contents