feat: add multi-environment build system and development tooling

[deanq]

Summary

Adds a comprehensive build system that supports multiple Python package managers (uv, pip, poetry, conda, pipenv) and establishes development workflow tooling for contributors.

Changes

Build System Infrastructure

• Makefile with auto-detection for 5 package managers
• pyproject.toml with dev dependencies and tool configurations
• Universal make dev command that works with any environment manager
• Quality gates: make quality-check and make quality-check-strict
• Helper commands: venv-info, clean-venv, update-deps, sync-deps

Dependency Management

• requirements.txt - pip-compatible lock file
• environment.yml - conda environment specification
• uv.lock - uv lock file with full dependency resolution
• Auto-generation via make sync-deps

Documentation

• DEVELOPMENT.md - comprehensive guide covering:
  • Environment setup for all package managers
  • Complete Makefile command reference
  • Development workflow and best practices
  • Code quality guidelines
  • Testing instructions
  • Troubleshooting guide
• README.md - updated with new setup methods and workflow

Development Tools

• ruff - linting and formatting
• mypy - type checking (lenient for examples)
• pytest - testing with async support and coverage

Benefits

1. Inclusive Setup - Users can contribute with their preferred package manager
2. Consistent Quality - Pre-commit quality checks ensure code standards
3. Better DX - Clear documentation and automated tooling reduce friction
4. CI/CD Ready - Quality gates designed for automated workflows
5. Cross-Platform - Dependency files for pip, conda, and uv users

Usage

Quick Start

# Setup (auto-detects your package manager)
make dev

# Check your environment
make venv-info

# Before committing
make quality-check

All Available Commands

Run make help to see all 16 available commands.

Testing Checklist

• Makefile auto-detection works with uv
• make dev installs dependencies successfully
• make lint runs without errors
• make format-check runs without errors
• make typecheck handles empty directories gracefully
• make quality-check passes all checks
• make sync-deps generates dependency files
• Documentation is clear and comprehensive
• README updated with new workflow

Commit Structure

Three logical commits for easy review:

1. feat: Build system infrastructure (pyproject.toml, Makefile)
2. build: Cross-platform dependency files (requirements.txt, environment.yml, uv.lock)
3. docs: Development guide and README updates (DEVELOPMENT.md, README.md)

---

Note: This establishes the foundation for consistent development practices across the flash-examples repository.

[linear]

AE-1471 Official Flash Examples repo

[Copilot]

Pull Request Overview

This PR establishes a comprehensive development infrastructure for the flash-examples repository by introducing multi-environment build system support and standardized development tooling. The changes enable contributors to use their preferred Python package manager while maintaining consistent code quality standards.

Key Changes:

• Implemented Makefile with auto-detection for 5 package managers (uv, pip, poetry, conda, pipenv)
• Added development dependencies and tool configurations in pyproject.toml
• Created comprehensive development documentation with setup guides and workflow instructions

Reviewed Changes

Copilot reviewed 5 out of 7 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
pyproject.toml	Defines project metadata, dependencies, and configuration for ruff, mypy, pytest, and coverage tools
environment.yml	Provides conda environment specification for conda users
Makefile	Implements build system with package manager auto-detection and quality gate commands
README.md	Updates setup instructions to reference new build system and development guide
DEVELOPMENT.md	Comprehensive 596-line guide covering environment setup, commands, workflows, and troubleshooting

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.