Proponer una pull request

Las pull requests son bienvenidas, de una errata a una nueva herramienta. Esta página da el camino a seguir; Desarrollo describe en detalle el repositorio y sus controles. Necesita una cuenta de GitHub, git, uv y just.

Primero hablar, después programar

Para todo lo que vaya más allá de una errata o una frase de documentación, abra o comente primero un issue — una propuesta de función o un informe de error — y diga que le gustaría encargarse. Acordar el enfoque antes de escribir el código evita reescribirlo.

Paso a paso

1. Haga un fork y clónelo. En GitHub, pulse Fork y clone su copia. Con la CLI de GitHub, en un solo comando:

   gh repo fork mathbeal/avenir-mcp --clone
   cd avenir-mcp

2. Instale y compruebe el punto de partida.

   uv sync       # Python 3.14 y las herramientas de desarrollo bloqueadas
   just check    # todo debe pasar antes de cambiar nada

3. Cree una rama con el nombre del cambio:

   git switch -c feat/subidas-suscripciones

4. Escriba primero la prueba, véala fallar y escriba el código que la hace pasar. Las pruebas solo usan datos inventados — nunca YNAB, nunca su plan. Amplíe el plan de demostración en evals/demo_budget.py si un ejemplo necesita cifras nuevas.

5. Ejecute los controles hasta que pasen todos:

   just fix       # formato
   just check     # ruff, pylint, mypy, pytest (100 % de cobertura), vocabulario, bloqueo
   just hygiene   # erratas, auditoría de workflows, licencias (REUSE)
   just secrets   # gitleaks sobre cada commit (con Docker)

6. Actualice la documentación. Si cambió una herramienta, sus argumentos o sus respuestas, ejecute uv run python -m docsgen y haga commit de lo que escribe. Una página escrita a mano se cambia en todos los idiomas del sitio a la vez; just docs construye el sitio y falla ante un enlace roto.

7. Haga commit con un prefijo que indique el tipo de cambio — el changelog se genera a partir de él:

   git commit -s -m "feat: list subscriptions whose price went up"

   -s añade el sign-off al commit: usted certifica el Developer Certificate of Origin — escribió el cambio, o tiene derecho a proponerlo bajo licencia MIT.

8. Suba la rama y abra la pull request.

   git push -u origin feat/subidas-suscripciones
   gh pr create --fill

   O ábrala desde el enlace que muestra GitHub. Rellene la plantilla: qué y por qué, cómo se comprobó, la lista de control, y Closes #<issue>.

Qué pasa después

Etapa	Qué esperar
CI	los mismos controles que just check y just hygiene, en Linux, macOS y Windows, la construcción de la documentación, el MCP Inspector, commits con sign-off y un título que empieza por el tipo de cambio; CI passed y MCP Inspector deben estar en verde. En una primera contribución, un mantenedor aprueba antes la ejecución.
Revisión	comentarios sobre el código; suba nuevos commits a la misma rama para responder
Fusión	agrupada en un solo commit en main, con el título de su pull request como mensaje
Versión	su cambio aparece en el changelog de la siguiente versión

Qué hace aceptar una pull request

• Un cambio por pull request, lo bastante pequeño para revisarlo de una vez.
• Pruebas escritas primero, que cubren cada línea y cada rama.
• Ninguna dependencia nueva de ejecución sin un motivo escrito en la pull request.
• Escrituras seguras: una herramienta que modifica el plan previsualiza, espera la confirmación y se puede deshacer — vea Seguridad por diseño.
• Ningún dato financiero real, en ningún sitio: código, pruebas, documentación, capturas.
• Cada commit con sign-off (git commit -s).

El contrato completo está en AGENTS.md, que se aplica tanto a las personas como a los agentes de código.