Richtlijnen voor bijdragen aan Toolbox Continu Inzicht

Het ontwikkelen van de Toolbox Continu Inzicht bestaat uit twee delen. Eerst ontwikkelt HKV de basisfunctionaliteit. Deze ontwikkeling is voor iedereen te volgen op GitHub, maar toevoegingen worden nog niet geaccepteerd. Daarna blijft het project open source beschikbaar en kan het verder worden ontwikkeld. De term ‘ontwikkelaars’ duidt in de eerste ontwikkelfase op het team van HKV, later op anderen die een bijdrage willen leveren. Een bijdrage kan uiteenlopen van een vraag tot een grote wijziging via een pull request.

Een bijdrage kan een van de volgend zaken zijn:

  1. Je hebt een vraag
  2. Je denkt een probleem (bug) te hebben gevonden (of onverwachte functionaliteit)
  3. Je wilt een aanpassing maken (bug fixen, nieuwe functionaliteit, update aan de documentatie)
  4. Je wilt een nieuwe versie publiceren

De onderstaande secties behandelen de stappen per geval.

Je hebt een vraag

  1. Gebruik de zoekfunctie hier om te kijken of iemand anders dezelfde vraag heeft.
  2. Als je niks vergelijkbaars kan vinden, maak een nieuwe issue aan.
  3. Voeg het "Question” label toe; voeg andere labels toe waar nodig.

Je denkt een probleem (bug) te hebben gevonden

  1. Gebruik de zoekfunctie hier om te kijken of iemand anders dezelfde vraag/probleem heeft.
  2. Als je niks vergelijkbaars kan vinden, maak een nieuwe issue aan. Zorg dat je genoeg informatie meegeeft zodat andere ontwikkelaars je probleem begrijpen en genoeg context hebben om je te helpen. Afhankelijk van je probleem, kan je de SHA hashcode van de commit die problemen veroorzaakt toevoegen. Denk daarnaast ook aan versie- en besturingssysteeminformatie.
  3. Voeg labels toe die relevant zijn voor je probleem.

Je wilt een aanpassing maken

  1. (Belangrijk) Communiceer aan de rest van de ontwikkelaars voor je begint dat je een aanpassing wilt maken. Dit laat je weten door een issue aan te maken.
  2. (Belangrijk) Bereik consensus over je idee.
  3. De hoofdontwikkelaars hebben rechten om nieuwe branches aan te maken. Als je deze rechten niet hebt, maak een 'fork' (kopie) in je eigen account. In deze fork maak je een eigen branch van de laatste commit in main. Probeer om veranderingen die in de tussentijd worden doorgevoerd op main al mee te nemen. Dit doe je door te pullen van de 'upstream' repository, (zie instructies hier en hier);
  4. Voor Visual Studio Code staat er een voorbeeldconfiguratie.
  5. Installeer de benodigde python packages in een pixi omgeving met pixi install, volg de uitleg van de pixi. Pixi zorgt er voor dat iedereen dezelfde versies van python packages heeft.
  6. Zorg dat de format van je code correct is met pixi run pre-commit. Pre-commit haalt opmaak fouten uit je code en zorgt voor een fijne manier van samenwerken. Hier onder vallen een aantal zaken als spaties, haakjes etc, maar ook docstrings. Door het installeren van pre-commit met de volgende commando: pre-commit install --hook-type pre-commit --hook-type pre-push runt deze lokaal automatisch met git commit actie.
  7. Zorg dat alle bestaande testen werken met pixi run pytest. Met pixi run pytest-cov wordt (lokaal) een html overzicht gegenereerd in de map tests/hidden_test_cov/index.html.
  8. Zorg dat alle documentatie automatisch genereert met pixi run quarto-render. Quarto is al onderdeel van de zojuist aangemaakte pixi omgeving.
  9. Voeg bij nieuwe functionaliteit altijd nieuwe tests toe.
  10. Update en voeg documentatie toe. Gebruik Numpy Style Python docstrings. Zorg dat je code leesbaar en begrijpelijk is voor anderen. De pydoclint checkt de doctring format voor je.
  11. Heb je nieuwe termen toegevoegd? Update dan de vertalingen in tabel
  12. Push je branch. naar (jouw fork van) de toolbox continu inzicht repo op GitHub;
  13. Maak een pull request aan, bijvoorbeeld volgens deze instructies. Pull requests die worden ontvangen, krijgen altijd een review.

Als je het idee heb dat je iets nuttig heb toegevoegd, maar je weet niet hoe je tests schrijft of runt of hoe je documentatie aanmaakt: geen probleem. Maak een pull request en dan kijken we hoe we kunnen helpen.

Je wilt een nieuwe versie publiceren

Dit is een stukje voor de hoofdontwikkelaars van toolbox continu inzicht.

  1. Checkout HEAD van de main branch met git checkout main en git pull.

  2. Beslis welke nieuwe versie (major, minor or patch) gebruikt gaat worden. We gebruiken semantic versioning.

  3. Omdat je niet direct naar de main branch kan schrijven (protected), maak een nieuwe branch aan met git checkout -b release-<version>.

  4. Indien dependencies zijn aangepast, maak een nieuw pixi lock bestand.

  5. Pas de versie aan in src/toolbox_continu_inzicht/__init__.py, de pyproject.toml leest deze uit.

  6. Pas de [docs/overig/changelog.qmd](overig/changelog.qmd) aan met de veranderingen. Vergeet de link naar de pull request niet.

  7. Zorg dat de format van je code correct is met pixi run ruff check.

  8. Zorg dat alle bestaande testen werken met pixi run pytest.

  9. Commit & push je aanpassingen naar GitHub.

  10. Maak een pull request aan, laat iemand het reviewen, wacht op alle acties, deze worden groen, en merge de pull request.

  11. Wacht tot de GitHub-acties op de main branch klaar zijn en er een groen vinkje bij staat.

  12. Maak een nieuwe 'release' aan op GitHub

    • Gebruik de versie als titel en pas een versie tag toe.
    • Als beschrijving gebruik de intro van de README.md en veranderingen uit de changelog.qmd.

  13. Check

    • Is de wiki bijgewerkt?
    • Heeft de GitHub actie alles naar PyPI gestuurd?
    • Werkt de nieuwe versie met: pip3 install toolbox_continu_inzicht==<new version>?

  14. Vier je nieuwe versie!