Product Requirements Document

Executive Summary

The Python Project Common repository provides a comprehensive suite of tools, templates, and workflows to streamline Python project development. It consists of three primary components: a Copier template for project scaffolding, reusable GitHub Actions workflows for CI/CD automation, and a Python package (emcd-projects) for project maintenance tasks.

The project aims to eliminate setup friction, ensure consistent quality standards, and reduce maintenance overhead for Python open source projects.

Problem Statement

Python developers and project maintainers face several recurring challenges:

Who experiences the problem: - Python package developers creating new projects - Open source maintainers managing multiple repositories - Development teams establishing consistent tooling standards - Contributors working across projects with different conventions

When and where it occurs: - During initial project setup and scaffolding - When establishing CI/CD pipelines for testing and deployment - While maintaining documentation sites and coverage reporting - When enforcing code quality standards across repositories

Impact and consequences: - Time wasted on repetitive setup tasks instead of feature development - Inconsistent tooling and quality standards across projects - Manual maintenance of documentation sites and coverage reports - Fragmented workflows requiring external services (ReadTheDocs, Codecov)

Current workarounds and limitations: - Manual project setup with copy-paste configuration - Individual GitHub Actions workflows duplicated across repositories - Reliance on external services for documentation hosting and reporting - Ad-hoc quality assurance processes without standardization

Goals and Objectives

Primary Objectives (Critical)

REQ-001: Rapid Project Bootstrapping (Critical)

Enable developers to create fully-configured Python projects in minutes, not hours. Success Metric: Project setup time reduced from 2+ hours to <5 minutes.

REQ-002: Consistent Quality Standards (Critical)

Enforce uniform code quality, testing, and documentation standards across all projects. Success Metric: 100% of generated projects pass linting, typing, and testing requirements.

REQ-003: Self-Contained Documentation (Critical)

Eliminate dependencies on external documentation and reporting services. Success Metric: Generated projects include complete static site infrastructure.

Secondary Objectives (High)

REQ-004: Multi-Platform CI/CD (High)

Provide comprehensive testing across Python versions and operating systems. Success Metric: Support for Python 3.9+ on Linux, macOS, and Windows.

REQ-005: Maintenance Automation (High)

Automate routine maintenance tasks for project lifecycle management. Success Metric: Reduce manual maintenance overhead by >75%.

Success Metrics - Project setup time: <5 minutes from template to working development environment - Quality gate compliance: 100% of generated projects pass all QA checks - Documentation coverage: Complete static site with versioned docs and reports - Template adoption: Measurable usage across multiple repositories - Maintenance efficiency: Automated badge generation and site updates

Target Users

Primary Users

Open Source Python Developers

  • Creating new Python packages or applications

  • Need: Rapid project setup with modern tooling

  • Proficiency: Intermediate to advanced Python knowledge

  • Context: Individual or small team development

Project Maintainers

  • Managing multiple Python repositories

  • Need: Consistent standards and automated maintenance

  • Proficiency: Advanced Python and DevOps experience

  • Context: Long-term project sustainability

Secondary Users

Development Teams

  • Establishing organizational Python project standards

  • Need: Reproducible project templates and workflows

  • Proficiency: Varied technical levels

  • Context: Enterprise or team environments

Contributors

  • Working on projects using this template system

  • Need: Clear development guidelines and tooling

  • Proficiency: Basic to intermediate Python knowledge

  • Context: Open source contribution workflows

Functional Requirements

Project Template System

REQ-006: Copier Template Integration (Critical)

As a developer, I want to generate new Python projects from a template so that I have consistent project structure and tooling.

Acceptance Criteria: - Template generates complete project structure with sources/, tests/, documentation/ - Includes configured pyproject.toml with Hatch build system - Provides pre-commit hooks and quality assurance tool configuration - Supports optional features (Rust extensions, CLI applications, GUI frameworks)

REQ-007: Development Environment Setup (Critical)

As a developer, I want automated development environment configuration so that I can start coding immediately.

Acceptance Criteria: - Hatch environment configuration for development, testing, and documentation - Pre-configured linting (Ruff), type checking (Pyright), and formatting tools - Optional property-based testing support (Hypothesis/proptest) - IDE integration support with proper Python path configuration

GitHub Actions Workflows

REQ-008: Multi-Platform Testing (Critical)

As a maintainer, I want automated testing across Python versions and platforms so that I ensure compatibility.

Acceptance Criteria: - Test matrix covering Python 3.9+ on Linux, macOS, Windows - Parallel test execution with coverage reporting - Failure notifications with detailed error information - Integration with project’s quality gates

REQ-009: Documentation Generation (High)

As a maintainer, I want automated documentation building and deployment so that users have current documentation.

Acceptance Criteria: - Sphinx documentation generation with multiple output formats - Versioned documentation with proper cross-linking - API documentation auto-generation from docstrings - Static site deployment without external dependencies

REQ-010: Package Publishing (High)

As a maintainer, I want automated package building and publishing so that releases are consistent and reliable.

Acceptance Criteria: - Automated wheel and source distribution building - PyPI publication with proper version management - Release asset generation and GitHub release creation - Optional binary executable generation (PyInstaller)

Project Maintenance Package

REQ-011: Static Website Management (Critical)

As a maintainer, I want automated static site maintenance so that documentation and reports stay current without manual intervention.

Acceptance Criteria: - Coverage badge generation from test results - Versioned documentation index maintenance - Static site hosting compatibility (GitHub Pages, etc.) - No dependency on external reporting services

REQ-012: Template Updates (Medium)

As a maintainer, I want tools to update existing projects when the template changes so that projects stay current with best practices.

Acceptance Criteria: - Copier update support for template changes - Conflict resolution guidance for manual modifications - Rollback capability for failed updates - Change impact assessment and reporting

Non-Functional Requirements

Performance Requirements - Template generation: Complete project setup in <30 seconds - CI/CD workflows: Test suite execution in <10 minutes for standard projects - Documentation builds: Complete site generation in <5 minutes

Compatibility Requirements - Python versions: Support Python 3.9 through latest stable version - Operating systems: Linux (Ubuntu), macOS, Windows - Package managers: Compatible with pip, uv, pipx installation methods - Version control: Git repository structure and conventions

Reliability Requirements - Template generation: 99.9% success rate for valid configurations - CI/CD workflows: <1% false positive failure rate - Documentation builds: Graceful degradation for missing optional components

Usability Requirements - Template prompts: Clear, self-documenting configuration questions - Error messages: Actionable guidance for common issues - Documentation: Complete setup and usage examples - Learning curve: New users productive within 1 hour

Security Requirements - No secrets exposure in generated configurations - Secure defaults for all optional components - Supply chain security through pinned workflow versions - Permission minimization for GitHub Actions

Constraints and Assumptions

Technical Constraints - Python ecosystem: Must work with standard Python packaging tools - GitHub integration: Workflows designed for GitHub Actions environment - Template system: Built on Copier templating framework - Static sites: Must be hostable without server-side processing

Project Constraints - Open source licensing: Apache 2.0 license compatibility required - Maintenance resources: Single maintainer with community contributions - Backward compatibility: Template updates must not break existing projects - Documentation: All features must be documented with examples

Dependencies - Copier: Project generation and updates - Hatch: Python environment and build management - GitHub Actions: CI/CD automation platform - Sphinx: Documentation generation system

Assumptions - Users have basic Git and Python knowledge - Projects follow semantic versioning conventions - Standard Python package structure is acceptable - GitHub is the primary hosting platform for repositories

Out of Scope

The following features will NOT be included to maintain focus and prevent scope creep:

Alternative Version Control Systems - Support for GitLab, Bitbucket, or other Git hosting platforms - Integration with Mercurial, SVN, or other VCS systems

Non-Python Language Support - Templates for other programming languages - Mixed-language project templates

Enterprise-Specific Features - LDAP/Active Directory integration - Enterprise security scanning tools - Proprietary CI/CD system integration

External Service Integration - ReadTheDocs, Codecov, or other third-party services - Slack, Discord, or other notification systems - Commercial quality assurance tools

Advanced Deployment Scenarios - Docker container orchestration - Cloud-specific deployment templates - Microservices architecture templates

For PRD format and guidance, see Requirements Documentation.