Skip to content

architecture.md

Latest commit

 

History

History
71 lines (51 loc) · 2.99 KB

architecture.md

File metadata and controls

71 lines (51 loc) · 2.99 KB
Raw

Architecture

mpt-extension-contrib is a uv workspace monorepo of independently released Python libraries for SoftwareONE MPT extensions.

Repository model

  • The root pyproject.toml defines the uv workspace and the shared tool configuration (ruff, flake8, mypy, pytest, coverage). It is not an installable distribution — there is no umbrella mpt-extension-contrib package.
  • A single uv.lock locks the whole workspace.
  • Each top-level directory is one independently released distribution. The live list of packages is the package table in the root README.md (kept in sync by make create-module).

Naming rule

For a module <module>:

Repository directory: <module>                          (kebab-case)
Distribution name:    mpt-extension-contrib-<module>
Python import:        mpt_extension_contrib.<module_with_underscores>

Directories and distribution names use hyphens; the Python import segment uses underscores.

Namespace package

All distributions share the PEP 420 namespace package mpt_extension_contrib. No distribution may contain mpt_extension_contrib/__init__.py — that file would claim the namespace and shadow sibling distributions installed alongside it. Only a concrete module directory owns an __init__.py, e.g. mpt_extension_contrib/shared/.

This invariant is enforced two ways:

See the "Two views" section of the README for the on-disk vs installed picture.

The shared module

shared/ (mpt-extension-contrib-shared) holds internal helpers reused by other contrib modules. It is internal API: extension repositories should not depend on it directly. It is released independently, and a breaking change to shared does not require updating every consumer in the same change — consumers bump their declared mpt-extension-contrib-shared constraint when they adopt a new release.

Release model

Each distribution is versioned and released independently:

  • a change limited to one module releases only that module;
  • a compatible change to shared is released before any consumer that needs it (the release workflow publishes in workspace order, one module at a time).

Git tags use <module>-<version>; each module gets its own GitHub Release. See releases.md.

CI

The PR workflow (.github/workflows/pr-build-merge.yml) classifies changed files with scripts/detect_changed_packages.py and builds/tests only the affected modules; a change to shared tooling fans out to every module. See contributing.md and testing.md.