Skip to content

🇬🇧 English · 🇪🇸 Español

puremacro — Ruta hacia la versión 1.0

Este documento declara qué significa lanzar puremacro 1.0, la política que entra en vigor con esa versión, y las condiciones concretas que el mantenedor se compromete a cumplir antes de etiquetarla. Es editable; se permiten revisiones en versiones previas a 1.0. El documento declara intención, no contrato.

1. Qué significa la versión 1.0

La versión 1.0 es el punto en que la API pública deja de renombrarse libremente. La convención pre-1.0 establecida en README.md — "las APIs se renombran libremente y los consumidores se actualizan en el mismo commit" — termina con la 1.0. A partir de ella, todo renombramiento o eliminación de un símbolo público pasa por un ciclo de obsolescencia (§ 2).

La API pública es el conjunto de símbolos listados en tests/fixtures/public_api_snapshot.json en la etiqueta de la 1.0. Todo lo que no figure en ese snapshot es detalle de implementación y puede cambiar sin aviso. Los subpaquetes explícitamente excluidos de la garantía de la 1.0 se listan en § 5.

El propósito de cortar la 1.0 no es "el paquete está terminado", sino "los usuarios pueden depender de esta superficie a través de versiones menores." La libertad de renombrar propia de la etapa pre-1.0 es incompatible con esa dependibilidad.

2. Política de obsolescencia (activa a partir de la 1.0)

Un símbolo público marcado para eliminación permanece invocable durante una versión menor con un DeprecationWarning. Ejemplo: puremacro.lp.foo declarado obsoleto en 1.3.0 → sigue siendo importable en 1.3.X (con advertencia) → eliminado en 1.4.0.

El texto de la advertencia debe indicar: 1. La ruta completamente calificada del símbolo obsoleto (puremacro.lp.foo, no solo foo). 2. La versión en que se eliminará (1.4.0). 3. El reemplazo canónico, o "sin reemplazo; se abre el issue X" si no se prevé ninguno.

Los cambios de comportamiento en símbolos existentes que modifiquen la forma del valor de retorno o la semántica de los argumentos requieren un incremento de versión mayor (1.X → 2.0), con la obsolescencia de la forma antigua en la versión 1.X anterior.

Las refactorizaciones internas que no cambien el snapshot de la API pública ni el comportamiento son versiones parche (1.X.Y → 1.X.Y+1).

Los límites entre versiones menores, mayores y parche los hace cumplir la Compuerta 3 (snapshot de la API pública) y el criterio del mantenedor sobre "si esto constituye un cambio de comportamiento" — no existe una verificación automatizada de equivalencia de comportamiento.

3. Contrato de congelamiento de API

tests/fixtures/public_api_snapshot.json es la fuente de verdad para "API pública". El fixture registra:

  • all: exportaciones de __all__ por subpaquete. Cada puremacro.X.symbol alcanzable desde el grafo de importación de puremacro/__init__.py con symbol in puremacro.X.__all__.
  • result_classes: nombres de campos de dataclass para cada tipo de resultado como dataclass congelada devuelto por un estimador público. Los nombres de campo son la API; los tipos y valores de los campos no forman parte del snapshot.

El fixture explícitamente NO registra: - Docstrings (revisables en cualquier momento). - Módulos internos (_*.py, p. ej. puremacro.lp._garch_utils). - puremacro.teaching.* (excluido por el salto de puremacro.teaching de la Compuerta 2). - puremacro.examples.* (no forma parte de la superficie del wheel). - Cuerpos de funciones y comportamiento. - Símbolos auxiliares / no incluidos en __all__ dentro de módulos públicos.

A partir de la 1.0, la Compuerta 3 se convierte en una compuerta de estabilidad, no en una compuerta de "diff contra la versión anterior". Cualquier diferencia es una acción deliberada del mantenedor; el archivo de snapshot es la fuente de verdad. Regenerar el snapshot fuera de un ciclo de obsolescencia es una violación de política.

4. Compuertas hacia la 1.0

Lista de verificación concreta. El mantenedor se compromete a cumplir todas estas condiciones antes de etiquetar la 1.0:

  • [ ] tests/known_failures.json::entries vacío durante tres versiones no-parche consecutivas. (Los parches mantienen el contador; las menores lo reinician.)
  • [x] CI de Pyodide real en verde. Incorporado en la 0.49.0 como Compuerta 6 en tools/release_check.py (activación opcional con --pyodide). Arranca Pyodide mediante Node, instala el wheel recién construido vía micropip, ejecuta pytest -m pyodide_smoke (8 pruebas curadas en 7 subpaquetes). En la 1.0 esto pasa a ser obligatorio (no opcional).
  • [x] Ruta de publicación en PyPI verificada. Completada el 2026-07-19: puremacro 0.92.0 subido a test.pypi.org (https://test.pypi.org/project/puremacro/0.92.0/) desde la compilación del repositorio independiente, y verificado de punta a punta — pip install desde test.pypi en un venv limpio devolvió un CholeskySVARResult funcional con el estimador del quickstart. PyPI de producción se hará mediante trusted publishing (release.yml en el repositorio independiente), reemplazando la especificación diferida tools/release_publish.py.
  • [ ] Todos los ejemplos en puremacro/examples/*.py tienen estado PASS o SKIP en docs/examples_gallery.json. Cero con FAIL.
  • [ ] Al menos un usuario externo ha instalado puremacro desde un artefacto de versión (wheel o sdist) y lo ha utilizado con éxito. "Externo" significa alguien distinto del mantenedor; "con éxito" significa que al menos un estimador devolvió la clase de resultado esperada en la máquina del usuario. Se trata de evidencia basada en criterio, no de una verificación de CI.
  • [ ] ARCHITECTURE.md actualizado dentro del último ciclo de versión. "Actualizado" = el mapa de módulos coincide con el árbol de directorios real sin entradas faltantes o desactualizadas.
  • [ ] Un RELEASING.md completo que cubra el procedimiento de publicación íntegro (actualmente solo la sección "Before tagging" de CONTRIBUTING.md lo cubre parcialmente).

Cuando las siete casillas estén marcadas, el mantenedor podrá etiquetar la 1.0. Hasta entonces, el paquete permanece en etapa pre-1.0 por omisión.

5. Alcance en la 1.0 vs. experimental

Tres categorías:

Estable en 1.0 (API estable a partir de la 1.0)

Los siguientes subpaquetes y sus entradas en el snapshot de la API pública son estables en la 1.0. Cualquier renombramiento, eliminación o cambio de comportamiento requiere el ciclo de obsolescencia de § 2.

  • puremacro.var.* (excepto var/regime/* y var/gvar)
  • puremacro.lp.* (excepto lp/_garch_utils)
  • puremacro.inference.*
  • puremacro.var.identify.*
  • puremacro.dsge.klein (el solver QZ tras el endurecimiento en la 0.47.0)
  • puremacro.volatility.*
  • puremacro.cycles, puremacro.cointegration_modern, puremacro.factor, puremacro.korv_gmm, puremacro.midas, puremacro.spectral, puremacro.synthetic_control, puremacro.wavelet, puremacro.realized_vol, puremacro.labor_share

Experimental de investigación (fuera de la garantía de la 1.0)

Estos módulos se incluyen en la 1.0 pero sus APIs pueden evolucionar en versiones menores 1.X sin el ciclo de obsolescencia. Documéntelos con un encabezado al inicio del módulo que indique su estado experimental.

  • puremacro.dsge.smets_wouters — puerto de Pfeifer a nivel de replicación; puede evolucionar cuando llegue la estimación SW07 (la especificación P1).
  • puremacro.dsge.gensys — nuevo en la 0.45.0; necesita al menos un usuario más antes de fijar la API.
  • puremacro.narrative.* — los esquemas pueden seguir evolucionando a medida que madura el trabajo sobre LUI/LWUI.
  • puremacro.uncertainty.* — en etapa inicial.
  • puremacro.models.* — modelos de investigación vinculados a artículos específicos (DMP con régimen dependiente, etc.); las revisiones de los artículos pueden forzar cambios en la API.
  • puremacro.var.regime.* — los VAR con cambio de régimen son experimentales de investigación.
  • puremacro.var.gvar — nuevo en la 2.5.0; necesita al menos un usuario más antes de fijar la API.
  • puremacro.causal.* (dml_plr, DoubleMLPLR, DMLResult, los aprendices lasso / ridge) — dentro de la 1.0, fuera de la garantía de la 1.0. Nuevo en la 3.4.0: se distribuye y queda cubierto por las verificaciones de pruebas y de snapshot de API de la compuerta de publicación, pero la superficie aún puede moverse en una versión menor 1.X. No existe un aprendiz de red elástica, y los incluidos son lineales en las columnas de X suministradas, de modo que una expansión de base o un learner= propio pueden alterar lo que la firma deba admitir.
  • puremacro.vfi.*, incluido hjb_achdou (solve_hjb_achdou, solve_kfe_achdou, solve_aiyagari_continuous_hjb) — los solucionadores en tiempo continuo alcanzaron su forma actual en la 3.4.0.
  • puremacro.spatial.* — los módulos de econometría espacial (spatial.weights, spatial.models, spatial.panel, spatial.lp) datan de las versiones 2.4.0-2.5.0; el solucionador de equilibrio general cuantitativo spatial.allen_arkolakis se incorporó en la 3.3.0 y se amplió en la 3.4.0 con el argumento backend=.
  • puremacro.dsge.occbin — solve_multiconstraint_occbin se incorporó en la 2.8.0 y se endureció en la 3.4.0 (empalme de regímenes, reporte de convergencia, validación de argumentos).
  • Cualquier subpaquete smm.* que se incorpore antes de la 1.0.

Canal secundario (fuera de la garantía de Pyodide y de la 1.0)

  • puremacro.teaching.* — envuelve intencionalmente statsmodels / linearmodels / arch para comparaciones de paridad con MATLAB. Documentado como artefacto docente, no como superficie de API de investigación.
  • puremacro.fetch.* — depende de servicios HTTP externos cuyos esquemas pueden cambiar independientemente del ciclo de versiones de puremacro. La superficie de fetch es de mejor esfuerzo.
  • puremacro.fetch.realtime.{banxico, inegi, bcb, bcch} — de mejor esfuerzo, como el resto de puremacro.fetch.*: cuatro APIs nacionales que pueden cambiar de endpoint, esquema o autenticación con independencia del ciclo de versiones de este paquete. El canario de esquema y la caché local de instantáneas existen precisamente porque esa superficie no está bajo nuestro control.
  • puremacro.bartik.*, puremacro.instruments.*, los constructores de pipelines de datos (build_panel, build_subnational_panel) — pragmáticamente estables, pero sus superficies están ligadas a flujos de trabajo de investigación que pueden cambiar. Trátelos como experimentales de investigación para la 1.0 a menos que se promuevan explícitamente.

Este documento se actualiza en cada versión pre-1.0. Cuando se publique la 1.0, los elementos relevantes aquí pasarán a ser política permanente del proyecto (probablemente en un POLICY.md o en un CONTRIBUTING.md ampliado).