Migration Guide: v2.x → v3.0¶
TL;DR — for almost every user, upgrading is a no-op. The 14 implemented packages' public API and behaviour are unchanged in v3.0. The only breaking change is the removal of seven empty placeholder packages that shipped no code, were never importable to any real effect, and had no tests. If your code imports only real MineProductivity APIs, it works on v3.0 without modification.
1. What changed¶
v3.0 is a production-readiness release, not a feature release. It hardens
packaging, the API contract, CI, and documentation. See CHANGELOG.md [3.0.0]
for the full list.
2. Breaking change: removed placeholder packages¶
The following empty packages were removed under ADR-0013:
| Removed module | Status before v3.0 | Where the responsibility lives now |
|---|---|---|
mineproductivity.benchmark |
7-line stub, no code | The top-level benchmark/ directory (scenarios + reports) |
mineproductivity.config |
7-line stub, no code | Configuration shape: mineproductivity.core.BaseConfiguration; sourcing is an application concern |
mineproductivity.exceptions |
7-line stub, no code | The exception hierarchy defined directly in mineproductivity.core |
mineproductivity.validation |
7-line stub, no code | mineproductivity.core.ValidationError + per-package validation |
mineproductivity.io |
7-line stub, no code | I/O lives in connectors / events |
mineproductivity.utils |
7-line stub, no code | No replacement needed - had no code |
mineproductivity.datasets |
7-line stub, no code | Test fixtures + the enterprise data generators |
mineproductivity.typing (non-package note dir) |
why.txt only, not importable |
Not applicable - never a package |
Each removed module had zero import references anywhere in the framework, tests, or examples, so the practical migration impact is effectively nil.
If you somehow imported one of these¶
You would have received an empty module. Replace the import as follows:
# before (v2.x) — imported an empty stub
from mineproductivity import config # or exceptions / validation / io / ...
# after (v3.0)
from mineproductivity.core import BaseConfiguration # configuration shape
from mineproductivity.core import ValidationError # validation errors
# exceptions: import the specific error you need from mineproductivity.core
3. Retained placeholders¶
mineproductivity.cli and mineproductivity.certification are retained (no
API yet); they remain chartered for future implementation. No action needed.
4. Plugin authors¶
If your plugin bounded its dependency to <3 (as the reference plugin did),
widen it once you have verified against v3.x - the public API it builds on is
unchanged:
# your _compat.py version gate
SUPPORTED_FRAMEWORK = VersionRange(min_version="2.0.0", max_version_exclusive="4.0.0")
The bundled reference plugin examples/plugins/sitepack has already been updated
this way and its full test suite passes against v3.0.
5. Packaging changes (non-breaking)¶
- A new
allextra installs every optional feature at once. - The
devextra now self-references the feature extras (same resolved set as before, no duplicated pins). - The
enterprisereporting stack is now on the dev/CI path.
Existing pip install mineproductivity[<extra>] invocations are unaffected.
6. Supported Python¶
Python 3.12 and 3.13 (unchanged from v2.x). See
SUPPORTED_VERSIONS.md.
7. Verification¶
After upgrading: