Lista de verificación de configuración del entorno

Python 3.14, uv, editor y configuración de herramientas: obtén desde la clonación hasta las pruebas en verde en minutos en macOS o Linux.

Cómo usar esta lista de verificación

• Completa en orden en una máquina nueva o en una clonación de repositorio nueva.
• Marca cada casilla antes de pasar a los pasos específicos de la aplicación.
• Si un paso falla, detente y soluciona el problema; no omitas los pasos de lockfile o venv.
• Pega las versiones exactas de pyproject.toml al informar problemas de configuración.

Runtime Principal

1. Instalar uv 0.6+: curl -LsSf https://astral.sh/uv/install.sh | sh o el administrador de paquetes según la política de la organización.
2. Instalar Python 3.14: uv python install 3.14 si no está instalado en todo el sistema.
3. Clonar repositorio: Clave SSH configurada; git clone git@github.com:acme/service.git.
4. Entrar al proyecto: cd service - confirma la presencia de pyproject.toml y uv.lock.
5. Sincronizar dependencias: uv sync --all-extras (o --extra dev según README).

Herramientas de Calidad

6. Ejecutar linter: uv run ruff check . - cero errores en una rama principal limpia.
7. Comprobar formato: uv run ruff format --check . o formatear una vez.
8. Ejecutar pruebas: uv run pytest -q - suite completa o subconjunto del README para la primera pasada.
9. Comprobación de tipos (si está configurada): uv run mypy src/ o uv run pyright.
10. Instalar pre-commit: uv run pre-commit install y luego pre-commit run --all-files.

Configuración de la Aplicación

11. Copiar plantilla de entorno: cp .env.example .env - completar los valores locales desde 1Password/documento de bóveda.
12. Nunca confirmar .env: Confirmar que está listado en .gitignore.
13. Base de datos (si es necesario): Docker compose docker compose up -d db o Postgres local documentado.
14. Migraciones: uv run alembic upgrade head o migrate de Django según el proyecto.
15. Iniciar servidor de desarrollo: uv run uvicorn app.main:app --reload - hacer curl /health.

Editor y Git

16. Intérprete de Python del editor: Apuntar a .venv/bin/python creado por uv.
17. Extensión Ruff: Formatear al guardar alineado con la longitud de línea de pyproject.toml.
18. Identidad de Git: user.name y user.email configurados (Configuración de Git).
19. GitHub CLI (opcional): gh auth login para el flujo de trabajo de PR.
20. PATH del shell: ~/.local/bin para herramientas pipx (httpie, copier).

Puerta de Verificación

21. Repetir CI localmente: Mismos comandos que en .github/workflows/pr.yml (ruff, pytest, mypy).
22. Prueba HTTP básica: curl -sf http://localhost:8000/health devuelve 200.
23. Saneamiento de importación: uv run python -c "import app" sin ImportError.
24. Bloqueadores documentados: Abrir un issue o hilo de Slack con la salida de error exacta si algún paso falla.
25. Confirmar con un compañero: Captura de pantalla o pegar el resumen de la terminal en el ticket de incorporación.

Preguntas frecuentes

Relacionados

• uv - La Cadena de Herramientas Rápida - Profundidad de uv
• Lista de verificación de incorporación de desarrolladores - rampa completa
• Python en la Shell - uso de la shell
• Gestión de versiones de Python - política de versiones

Versiones de la pila: Esta página se escribió para Python 3.14.0 (estable 3.14, mantenimiento 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+ y uv 0.6+.