Een pull request voorstellen

Pull requests zijn welkom, van een typfout tot een nieuwe tool. Deze pagina is het pad om te volgen; Ontwikkeling beschrijft de repository en zijn controles in detail. Je hebt een GitHub-account nodig, git, uv en just.

Eerst praten, dan programmeren

Voor alles wat groter is dan een typfout of een zin documentatie, open je eerst een issue of reageer je op een issue – een functieverzoek of een bugmelding – en zeg je dat je het graag wilt doen. Het eens worden over de aanpak voordat je code schrijft, bespaart je het herschrijven.

Stap voor stap

1. Forken en klonen. Klik op GitHub op Fork en kloon dan je kopie. Met de GitHub CLI, in één commando:

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

2. Installeren en het vertrekpunt controleren.

   uv sync       # Python 3.14 en de vastgelegde ontwikkeltools
   just check    # alles moet slagen voordat je iets verandert

3. Maak een branch met de naam van de wijziging:

   git switch -c feat/subscription-increases

4. Schrijf eerst de test, zie hem falen, en schrijf dan de code die hem laat slagen. Tests gebruiken alleen verzonnen gegevens – nooit YNAB, nooit je plan. Vul het demoplan in evals/demo_budget.py aan als een voorbeeld nieuwe cijfers nodig heeft.

5. Draai de controles tot ze allemaal slagen:

   just fix       # opmaak
   just check     # ruff, pylint, mypy, pytest (100 % dekking), woordenschat, lock
   just hygiene   # typos, controle van de workflows
   just secrets   # gitleaks op elke commit (vraagt Docker)

6. Werk de documentatie bij. Als een tool, zijn argumenten of zijn antwoorden zijn veranderd, draai je uv run python -m docsgen en commit je wat het schrijft. Een met de hand geschreven pagina wordt in alle talen van de site tegelijk gewijzigd; just docs bouwt de site en faalt bij een kapotte link.

7. Commit met een voorvoegsel dat het soort wijziging noemt – de changelog wordt eruit gegenereerd:

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

   -s tekent de commit af: je verklaart het Developer Certificate of Origin – je hebt de wijziging geschreven, of hebt het recht haar onder de MIT-licentie in te dienen.

8. Pushen en het pull request openen.

   git push -u origin feat/subscription-increases
   gh pr create --fill

   Of open het via de link die GitHub toont. Vul het sjabloon in: wat en waarom, hoe het is gecontroleerd, de checklist, en Closes #<issue>.

Wat er daarna gebeurt

Fase	Wat je kunt verwachten
CI	dezelfde controles als just check en just hygiene, op Linux, macOS en Windows, de build van de documentatie, de MCP Inspector, afgetekende commits en een titel die met het soort wijziging begint; CI passed en MCP Inspector moeten groen zijn. Bij een eerste bijdrage keurt een maintainer de run eerst goed.
Review	reacties op de code; push nieuwe commits naar dezelfde branch om erop te antwoorden
Merge	samengevoegd tot één commit op main, met de titel van je pull request als bericht
Release	je wijziging verschijnt in de changelog van de volgende versie

Wat een pull request mergeklaar maakt

• Eén wijziging per pull request, klein genoeg om in één keer te beoordelen.
• Eerst tests geschreven, die elke regel en vertakking dekken.
• Geen nieuwe runtime-afhankelijkheid zonder een reden in het pull request.
• Schrijfacties blijven veilig: een tool die het plan wijzigt, toont een voorbeeld, wacht op bevestiging en kan ongedaan worden gemaakt – zie Veilig door ontwerp.
• Geen echte financiële gegevens, nergens: code, tests, documentatie, schermafbeeldingen.
• Elke commit afgetekend (git commit -s).

Het volledige contract staat in AGENTS.md, dat geldt voor mensen en codeeragents.