RFC: Developer Experience Improvements

# RFC: Developer Experience Improvements for Mango Tango CLI

## 🎯 Executive Summary

This RFC proposes a series of developer experience improvements to streamline onboarding, standardize development workflows, and modernize our tooling while maintaining backward compatibility and cross-platform support.

**TL;DR**: Unify bootstrap scripts, modernize dependency management, add optional advanced tooling, improve cross-platform support.

## 🔍 Current Pain Points

Based on recent contributor experience and project analysis, we've identified several areas for improvement:

1. **Platform inconsistencies**: Different setup experiences across macOS/Linux/Windows
2. **Bootstrap complexity**: Separate shell scripts with assumptions about existing Python setup
3. **Dependency management**: Mixed approach with requirements*.txt files
4. **Windows/WSL clarity**: Unclear requirements for Windows contributors
5. **Tool fragmentation**: Limited standardization of development tasks

## 🚀 Proposed Solutions

### 1. Unified Cross-Platform Bootstrap

**Current state:**
```bash
# macOS/Linux
./bootstrap.sh

# Windows  
./bootstrap.ps1
```

**Proposed:**
```bash
# All platforms
./setup.sh
```

**Benefits:**
- Single script to maintain
- Handles Python 3.12 detection/guidance
- WSL detection for Windows users
- Better error messages and recovery

### 2. Modern Python Packaging

**Current state:**
```
requirements.txt
requirements-dev.txt
```

**Proposed:**
```toml
# pyproject.toml
[project]
dependencies = ["polars==1.9.0", "pydantic==2.9.1", ...]

[project.optional-dependencies]
dev = ["black==24.10.0", "isort==5.13.2", "pytest==8.3.4", ...]
```

**Benefits:**
- Single source of truth for dependencies
- Better integration with modern Python tooling
- Supports optional dependency groups
- Industry standard approach

### 3. Standardized Development Workflow

**Current state:**
```bash
# Manual commands, varies by contributor
black .
isort .
pytest
python -m pyinstaller pyinstaller.spec
```

**Proposed:**
```bash
# Primary workflow - mise tasks for all contributors
mise run format
mise run test
mise run build
mise run setup

# Fallback compatibility - Python scripts
python -m scripts.format
python -m scripts.test
python -m scripts.build
```

**Benefits:**
- **mise (primary)**: Intelligent caching, parallel execution, self-documenting (`mise tasks ls`)
- **Python fallback**: Ensures compatibility if mise has issues
- **Consistent interface**: Same commands work across all environments
- **IDE-agnostic**: Works with any editor or development setup

### 4. Modern Python Tooling Integration

**Current state:**
```bash
# Traditional Python tooling
python -m venv venv
source venv/bin/activate  # Manual activation required
pip install -r requirements-dev.txt
```

**Proposed:**
```bash
# Modern tooling with seamless integration
uv venv  # Fast virtual environment creation
mise install  # Tool version management + auto venv activation
uv pip install -e .[dev]  # 10-100x faster package installation
```

**Benefits:**
- **uv virtual environments**: Faster venv creation and package installation
- **mise + uv integration**: Automatic virtual environment activation when entering project directory
- **Seamless workflow**: No manual activation needed - `mise run test` just works
- **Performance**: 10-100x faster dependency installation and resolution
- **Tool coordination**: mise manages Python/uv versions, uv handles packages and environments
- **Flexible installation**: mise can be installed globally or locally per project

## 📋 Implementation Approach

### Core Changes
- [ ] Create unified `setup.sh` script
- [ ] Migrate dependencies to `pyproject.toml`
- [ ] Implement mise task runner for all contributors
- [ ] Add universal dev scripts as fallback
- [ ] Enhance pre-commit hooks
- [ ] Update documentation and guides
- [ ] CI/CD optimizations

## 🤔 Discussion Points

We'd love your input on:

1. **Tool preferences**: Any concerns about the proposed tooling choices (mise, uv, pyproject.toml)?

2. **IDE configurations**: Should we include IDE-specific configs or keep things universal?

3. **Onboarding priorities**: What's most important for new contributor experience?

4. **Development workflow**: Are there other common tasks that should be standardized?

## ✅ Benefits Summary

**For New Contributors:**
- 5-minute setup from clone to running app
- Clear, consistent instructions across all platforms
- Better error handling and recovery

**For Existing Contributors:**
- Backward compatible during transition
- Standardized tooling across all contributors
- Improved daily development workflows

**For Project Maintenance:**
- Single bootstrap script to maintain
- Modern dependency management
- Reduced platform-specific support burden

## 🔄 Migration Strategy

- Clear migration guide for existing contributors
- Temporary support for existing workflows during transition
- New contributors start with modern tooling from day one
- mise will become the standard development interface

## 📚 References

- [PEP 621 - Python Project Metadata](https://peps.python.org/pep-0621/)
- [mise Task Runner Documentation](https://mise.jdx.dev/)
- [uv: An extremely fast Python package installer](https://github.com/astral-sh/uv)
- [uv Documentation](https://docs.astral.sh/uv/)
- [Using uv with mise](https://mise.jdx.dev/mise-cookbook/python.html#mise-uv)

---

<details>
<summary><h2>📋 DRAFT Detailed Implementation Plan</h2></summary>

## Current State Assessment

**Existing Setup Analysis:**
- **Current tooling**: Standard Python venv + pip workflow for most contributors
- **Recent adoption**: mise + uv (likely not adopted by contributors yet)  
- **Bootstrap approach**: Separate bootstrap.sh/bootstrap.ps1 scripts
- **Dependency management**: Mixed approach (requirements*.txt files)
- **Platform support**: Cross-platform but with different setup experiences
- **IDE configs**: Minimal configurations to avoid confusion

**Key Challenges Identified:**
1. **Chicken-and-egg problem**: Bootstrap scripts assume Python 3.12 already exists
2. **Windows support gap**: Unclear WSL requirements vs native Windows support
3. **Tooling migration**: Need gradual transition path for existing contributors
4. **Cross-platform inconsistencies**: Different setup experiences across OS

## Phase 1: Foundation & Modern Tooling Migration

### 1.1 Unified Cross-Platform Bootstrap Script
- **Create enhanced `setup.sh`** - Single robust shell script replacing both bootstrap scripts
- **Features**:
  - Python 3.12 detection and installation guidance
  - Cross-platform virtual environment creation
  - Windows/WSL detection with appropriate guidance
  - Graceful fallback for missing dependencies
  - Environment validation and health checks
  - Clear error messages and recovery instructions

### 1.2 Windows Strategy & WSL Handling
- **WSL Detection**: Script detects if running in WSL vs native Windows
- **Platform Guidance**: Clear instructions for Windows users on WSL requirements
- **Fallback Support**: Native Windows batch script if WSL not required
- **Documentation**: Platform-specific setup guides

### 1.3 Modern Python Packaging Migration
- **Enhance `pyproject.toml`** with comprehensive project metadata
- **Centralize dependencies**: Migrate from requirements*.txt to pyproject.toml dependency groups
- **Tool configurations**: Consolidate black, isort, pytest, coverage settings
- **Build system**: Modern setuptools configuration with entry points
- **Backward compatibility**: Maintain requirements.txt during transition period

## Phase 2: Developer Workflow Optimization

### 2.1 Universal Task Management
- **mise integration** for all contributors
- **Python-based dev scripts** as fallback compatibility:
  - `python -m scripts.setup` - Environment setup and validation
  - `python -m scripts.test` - Test runner with options
  - `python -m scripts.format` - Code formatting (black + isort)
  - `python -m scripts.lint` - Comprehensive linting
  - `python -m scripts.build` - Build executable
  - `python -m scripts.health` - Environment health check

### 2.2 IDE-Agnostic Configuration
- **Enhanced pyproject.toml**: Centralized tool configurations work with all IDEs
- **EditorConfig**: Universal formatting rules across editors
- **Language Server Protocol**: Ensure compatibility with various IDE setups
- **Minimal IDE configs**: Only essential settings, avoid vendor lock-in
- **Setup documentation**: IDE-specific guidance as optional supplements

### 2.3 Git Workflow & Quality Assurance
- **Enhanced pre-commit hooks**:
  - Fast formatting (incremental, only changed files)
  - Import sorting with conflict resolution
  - Test execution for affected modules
  - Dependency security scanning
- **Commit templates**: Standardized commit message formats
- **PR templates**: Development checklist for contributors

## Phase 3: Migration & Adoption Strategy

### 3.1 Tooling Migration
- **Universal mise adoption**: All contributors use standardized commands
- **Clear migration path**: Step-by-step guide for existing contributors
- **Documentation**: Benefits and usage of modern tooling

### 3.2 Contributor Onboarding Enhancement
- **Interactive setup**: Guided onboarding with validation steps
- **Environment diagnostics**: Automatic problem detection and solutions
- **Success verification**: End-to-end testing of development environment
- **Recovery procedures**: Fix common setup issues automatically

### 3.3 Development Environment Automation
- **Smart dependency management**: Detect and resolve version conflicts
- **Health monitoring**: Regular environment validation
- **Update automation**: Guided dependency updates with testing
- **Performance tracking**: Monitor setup and build times

## Phase 4: CI/CD & Build Optimization

### 4.1 Modern CI/CD Pipeline Enhancement
- **GitHub Actions optimization**: Leverage uv for faster CI when available
- **Matrix testing**: Multiple Python versions and platforms
- **Intelligent caching**: Dependencies, test results, build artifacts
- **Parallel execution**: Tests, formatting, security scans
- **Cross-platform builds**: Windows, macOS, Linux executables

### 4.2 Build System Modernization
- **PyInstaller optimization**: Faster builds, smaller executables
- **Release automation**: Version bumping, changelog generation
- **Distribution packaging**: Multiple formats (wheel, executable, containers)
- **Security scanning**: Automated vulnerability detection

## Success Metrics
- **Setup time**: < 5 minutes from clone to working `python -m mangotango`
- **Cross-platform consistency**: Identical experience on macOS/Linux/Windows
- **Error recovery**: Clear guidance and automatic fixes for common issues
- **Migration success**: Smooth transition for existing contributors
- **Developer satisfaction**: Improved onboarding and daily workflow experience

## Key Deliverables
1. **Enhanced setup.sh**: Robust cross-platform bootstrap script
2. **Modernized pyproject.toml**: Centralized dependency and tool configuration
3. **mise task definitions**: Standardized commands for all development tasks
4. **Universal dev scripts**: Python-based fallback task runners
5. **Migration documentation**: Clear transition guides for contributors
6. **Enhanced CI/CD**: Modern pipeline with performance optimizations
7. **Comprehensive docs**: Setup, development, and troubleshooting guides

</details>

---

**What do you think?** Please share your thoughts, concerns, or alternative suggestions. This is meant to be a collaborative discussion to improve the developer experience for everyone! 🙏

RFC: Developer Experience Improvements #174

Description

RFC: Developer Experience Improvements for Mango Tango CLI

🎯 Executive Summary

🔍 Current Pain Points

🚀 Proposed Solutions

1. Unified Cross-Platform Bootstrap

2. Modern Python Packaging

3. Standardized Development Workflow

4. Modern Python Tooling Integration

📋 Implementation Approach

Core Changes

🤔 Discussion Points

✅ Benefits Summary

🔄 Migration Strategy

📚 References

📋 DRAFT Detailed Implementation Plan

Current State Assessment

Phase 1: Foundation & Modern Tooling Migration

1.1 Unified Cross-Platform Bootstrap Script

1.2 Windows Strategy & WSL Handling

1.3 Modern Python Packaging Migration

Phase 2: Developer Workflow Optimization

2.1 Universal Task Management

2.2 IDE-Agnostic Configuration

2.3 Git Workflow & Quality Assurance

Phase 3: Migration & Adoption Strategy

3.1 Tooling Migration

3.2 Contributor Onboarding Enhancement

3.3 Development Environment Automation

Phase 4: CI/CD & Build Optimization

4.1 Modern CI/CD Pipeline Enhancement

4.2 Build System Modernization

Success Metrics

Key Deliverables

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions