ADR-0001: Seedling Template Design Philosophy¶
“Design is not just what it looks like and feels like. Design is how it works.” — Steve Jobs
Status¶
Accepted
Context¶
We need a world-class Python project template that provides:
Modern development workflow with best practices
Comprehensive CI/CD pipeline
Excellent developer experience
AI agent compatibility
Enterprise-grade quality standards
Reproducible project generation
Decision¶
Build the seedling template using Copier + uv + Nox + Just + Sphinx + pre-commit-ci as the core technology stack.
Consequences¶
Positive Consequences¶
Copier (Template Engine)¶
Jinja2 templating: More powerful than Cookiecutter’s limited templating
Better dependency management: Handles template updates and dependencies
Modern Python support: Built with modern Python practices
Version control integration: Better git integration and update handling
Conditional templating: Advanced logic for conditional file generation
uv (Package Manager)¶
10-100x faster than pip: Dramatically improved installation speed
Lockfile advantages: Reproducible builds with uv.lock
Modern Python tooling: Built for modern Python development
Modern Python tooling: Built for modern Python development
Cross-platform: Works consistently across all platforms
Nox (Build System)¶
Multi-environment testing: Test against multiple Python versions
Session management: Clean separation of different tasks
CI integration: Perfect integration with GitHub Actions
Extensible: Easy to add new sessions and tasks
Python-native: Built specifically for Python projects
Just (Task Runner)¶
Cross-platform compatibility: Works on Windows, macOS, and Linux
Dependency management: Handles task dependencies automatically
Readability: Simple, readable syntax
No dependencies: Single binary, no Python installation required
IDE integration: Works well with modern IDEs
Sphinx (Documentation)¶
Documentation standards: Industry standard for Python documentation
Extensibility: Rich ecosystem of extensions
Hosting integration: Perfect for GitHub Pages deployment
Search functionality: Built-in search capabilities
Versioning: Support for multiple documentation versions
pre-commit-ci (Quality Assurance)¶
Automated quality enforcement: Runs quality checks on every PR
Team collaboration: Ensures consistent code quality across team
Auto-fix capabilities: Automatically fixes formatting issues
GitHub integration: Seamless integration with GitHub workflows
Configurable: Flexible configuration for different project needs
Negative Consequences¶
Learning Curve¶
New tools: Team members need to learn uv, Nox, and Just
Template complexity: More complex than simple cookiecutter templates
Configuration overhead: More configuration files to maintain
Dependencies¶
Tool requirements: Requires specific versions of tools
Platform considerations: Some tools may have platform-specific issues
Update management: Need to keep template and tools in sync
Maintenance¶
Template maintenance: More complex template to maintain
Documentation: Need to document template usage and customization
Testing: More complex testing requirements for template
Implementation Details¶
Template Structure¶
seedling/
├── copier.yml # Template configuration
├── seedling/ # Template files
│ ├── src/{{ project_slug }}/
│ ├── tests/
│ ├── docs/
│ ├── .github/workflows/
│ └── *.jinja files
└── docs/ # Template documentation
└── adr/ # Architecture Decision Records
Key Design Principles¶
Modularity: Each tool has a specific, well-defined role
Extensibility: Easy to add new features and customizations
Consistency: Consistent patterns across all generated projects
Quality: Built-in quality gates and best practices
Modern: Uses latest Python development practices
Quality Standards¶
Type Safety: Full MyPy integration with strict mode
Code Quality: Ruff linting with comprehensive rules
Test Coverage: Minimum 80% coverage requirement
Documentation: Comprehensive docstrings and examples
Security: Regular dependency vulnerability scanning