Cómo contribuir

urg-forecast-core es una base abierta, mantenida en la medida de lo posible. Haz un fork, adáptalo a tu establecimiento o úsalo dentro de tu propio producto. Los issues y pull requests son bienvenidos; mientras esté en 0.x, la API puede cambiar entre versiones menores. Si necesitas soporte comercial o un desarrollo a medida sobre esta base, contacta al autor.

Toda participación se rige por el Código de Conducta.

Reportar problemas y pedir ayuda

• Errores y propuestas: abre un issue en https://github.com/nicoveraz/urg-forecast-core/issues. Si es un error, incluye la versión (urg-forecast --version), la versión de Python, el sistema operativo, el comando que corriste y el mensaje de error completo.
• Preguntas de uso: abre un issue con la etiqueta question.
• Seguridad: revisa la política de seguridad; no abras un issue público por una posible vulnerabilidad.

No pegues datos de pacientes en issues ni pull requests.

Proponer cambios

Haz un fork, crea una rama y abre un pull request contra main. Antes de subirlo, revisa que pasen las verificaciones de abajo; el CI corre lo mismo (lint, formato, tests en Python 3.11 y 3.12, build e instalación del wheel) en cada pull request.

La documentación se escribe primero en español (README.md, docs/). La traducción al inglés (README.en.md) se actualiza cuando corresponde. Los docstrings y comentarios del código van en inglés.

El sitio (https://nicoveraz.github.io/urg-forecast-core/) se arma con Astro Starlight en sitio/. Sus páginas se generan del README, de docs/, del CHANGELOG y de este archivo, CODE_OF_CONDUCT.md y SECURITY.md (sitio/scripts/sync.mjs): Inicio, Uso, Extender y Acerca de son secciones del README marcadas con comentarios <!-- sitio:... -->, así que se editan en el README. La página Demo lee los pronósticos que el workflow semanal datos.yml publica en la rama datos; para probarla localmente, copia la carpeta demo/ de esa rama a sitio/public/datos/. Para verlo localmente (Node 22):

cd sitio && npm ci && npm run dev

Desarrollo

uv sync --dev                # paquete + herramientas de desarrollo
uv run pytest -q             # tests
uv run ruff check .          # lint
uv run ruff format .         # formato (ruff es el único formateador)
pre-commit install           # opcional: lint y formato al hacer commit

El paquete usa estructura src/ y una sola instalación, sin extras. La idea es que siga siendo chico: el alcance es el pronóstico semanal con datos DEIS más lo necesario para extenderlo. Los modelos nuevos van en src/urgencias_core/models/ y se registran en pipeline.extra_models() y MODEL_INFO, con su sección en docs/modelos.md. El análisis por atención y la simulación quedan fuera de este repositorio.

Publicar una versión

Esta sección es para quien mantiene el repositorio; para contribuir basta con abrir un pull request.

Las versiones se publican en PyPI con Trusted Publishing (OIDC) desde .github/workflows/publish.yml, sin tokens guardados como secretos.

Configuración única:

• En PyPI, agrega este repositorio, el workflow publish.yml y el entorno pypi como publicador de confianza del proyecto urg-forecast-core. Deja el publicador restringido a ese entorno.
• En GitHub (Settings → Environments → pypi), limita los despliegues a tags v* y agrega al mantenedor como revisor obligatorio.

En cada versión:

1. Sube version en pyproject.toml (semver) y en CITATION.cff.

2. Mueve las notas de ## [Sin publicar] en CHANGELOG.md a un nuevo encabezado ## [X.Y.Z] - AAAA-MM-DD y actualiza los enlaces de comparación.

3. Haz commit, crea el tag y súbelo:

   git tag vX.Y.Z
   git push origin main --tags

El workflow publish corre los tests, verifica que el tag coincida con la versión del paquete y construye. Luego el job pypi-publish queda en pausa hasta que un revisor lo apruebe: abre la ejecución en la pestaña Actions y usa “Review deployments” → Approve. Tras la aprobación publica en PyPI y crea el release en GitHub con la sección del changelog como notas. No crees el release a mano (con gh release create o desde la web): el workflow lo hace, y Zenodo archiva cada release en cuanto se publica, así que borrarlo y recrearlo puede generar un DOI duplicado.

Archivo en Zenodo (DOI para citar)

Cada release se archiva en Zenodo. Los metadatos del archivo salen de .zenodo.json; CITATION.cff define la cita que muestra GitHub. La integración ya está activa: Zenodo detecta el release de GitHub y genera un DOI de versión, además del DOI concepto (10.5281/zenodo.21449610), que siempre apunta a la última versión.

El ORCID y la afiliación del autor están en CITATION.cff y .zenodo.json; mantenlos sincronizados si cambia la autoría.