Design Decision Document: Python Build Backend Selection - kuhl-haus/kuhl-haus-metrics GitHub Wiki

Project: kuhl-haus Package Ecosystem

Problem Statement

The current build system (setuptools) lacks support for PEP 639 licensing, generating deprecation warnings and creating technical debt that must be addressed before February 2026.

Options Considered

• Setuptools: Traditional, mature but lacks PEP 639 support
• Hatchling: Modern, supports PEP 639, balanced approach
• Flit: Simple but lacks PEP 639 support
• PDM: Full-featured with package management and PEP 639 support

Decision Matrix

Criterion	Setuptools	Hatchling	Flit	PDM
PEP 639 Support	❌ (2026)	✅	❌	✅
Maturity	★★★★★	★★★☆☆	★★★★☆	★★★☆☆
Simplicity	★★☆☆☆	★★★★☆	★★★★★	★★★☆☆
Features	★★★★★	★★★☆☆	★★☆☆☆	★★★★☆
Workspace Support	❌	❌	❌	✅
Git Dependencies	✅	✅	✅	✅

Design Decision

Selected: PDM with Git references as primary approach

Rationale

• PEP 639 Compliance: Immediate support avoids technical debt
• Dependency Management: Superior handling of the multi-package namespace structure
• Flexibility: Supports both Git references (simple) and workspaces (when needed)
• Familiarity: Git references approach mirrors Golang dependency management
• Future Compatibility: Modern approach aligns with Python packaging direction

Implementation Approach

• Primary Method: Git references for day-to-day development (simpler setup)
• Secondary Method: Workspaces for complex cross-package development scenarios
• Package Structure: Maintain separate repositories with clear dependency chains
• Versioning: Use Git tags/commits for version stability

Future Considerations

• Evaluate migration to workspaces if cross-package development increases
• Monitor setuptools PEP 639 implementation timeline
• Consider CI/CD pipeline optimizations for the chosen approach