Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Stap 10: Richt technische infrastructuur in

Open source samenwerking vraagt om technische infrastructuur: waar staat de code, hoe beheer je versies, hoe documenteer je, en hoe release je nieuwe versies? Deze stap helpt je de technische basis op orde te krijgen.

Goed ingerichte technische infrastructuur maakt samenwerken makkelijk en voorkomt chaos. Het hoeft niet perfect, maar wel praktisch werkbaar.

1. Code repository platform

De code repository is het centrale punt waar alle broncode staat. Het platform moet ondersteunen: versiebeheer, samenwerken, code review, en issue tracking.

GitHub

Kenmerken:

  • Meest populaire platform wereldwijd
  • Gratis voor publieke repositories
  • Uitgebreide tooling (Actions, Projects, Discussions)
  • Grote community en veel integraties

Voordelen:

  • Developers zijn ermee vertrouwd
  • Zichtbaarheid: mensen vinden je project makkelijk
  • Veel documentatie en ondersteuning
  • CI/CD via GitHub Actions

Nadelen:

  • Eigendom Microsoft (kan bezwaar zijn)
  • Data staat in VS (privacy-overwegingen)

Geschikt voor: Meeste gemeentelijke projecten. Standaardkeuze tenzij je specifieke redenen hebt om anders te kiezen.

GitLab

Kenmerken:

  • Open source platform (kan zelf hosten)
  • Gratis cloud-versie (gitlab.com)
  • Uitgebreide DevOps-functionaliteit ingebouwd
  • Sterke CI/CD

Voordelen:

  • Kan zelf gehost worden (volledige controle)
  • Europese cloud-optie beschikbaar
  • Alles-in-één platform (planning, CI/CD, security)

Nadelen:

  • Minder zichtbaar dan GitHub
  • Self-hosting vraagt onderhoud en expertise
  • Interface kan complex zijn

Geschikt voor: Wanneer je specifiek Europese hosting wilt of volledige controle door self-hosting nodig hebt.

code.overheid.nl

Kenmerken:

  • Catalogus van Nederlandse overheids-software
  • Geen hosting, maar verwijzingen naar repositories
  • Beheerd door VNG en Logius

Gebruik:

Je host code op GitHub/GitLab, maar registreert project ook op code.overheid.nl voor vindbaarheid binnen overheidssector.

Aanbeveling: Gebruik GitHub of GitLab voor hosting, en registreer je project aanvullend op code.overheid.nl voor zichtbaarheid.

2. Repository-structuur en branching

Hoe organiseer je de code in de repository? Een heldere structuur voorkomt verwarring.

Repository-structuur

Minimaal aanwezig:

  • README.md: Wat is dit project? Hoe installeren? Hoe gebruiken?
  • LICENSE / LICENTIE.txt: Volledige tekst van de open source licentie
  • CONTRIBUTING.md: Hoe kunnen anderen bijdragen?
  • Code of Conduct: Gedragsregels voor community

Verder structuur:

  • /src of /app: Broncode
  • /docs: Documentatie
  • /tests: Geautomatiseerde tests
  • /examples: Voorbeeldcode

Branching strategie

Branches (vertakkingen) helpen om verschillende versies parallel te ontwikkelen. Voor gemeentelijke samenwerking volstaat vaak een eenvoudig model:

Simpel model (aanbevolen voor starten):

  • main / master: Stabiele, productie-klare code
  • feature branches: Voor nieuwe functionaliteit (bijv. feature/vergunningen)
  • bugfix branches: Voor bug fixes

Uitgebreider model (bij intensieve ontwikkeling):

  • main: Productie
  • develop: Ontwikkelversie
  • release/x.y: Voorbereiden releases
  • feature/…: Nieuwe features

Tip: Start simpel. Je kunt altijd complexer worden als de samenwerking groeit.

3. Code review en kwaliteit

Open source betekent niet ‘alles mag’. Code review zorgt voor kwaliteit en kennisdeling.

Pull Request workflow

Wijzigingen worden niet direct in main gezet, maar via Pull Requests (GitHub) of Merge Requests (GitLab):

  • Developer maakt feature branch
  • Schrijft code + tests
  • Opent Pull Request met beschrijving
  • Anderen reviewen de code
  • Na goedkeuring: merge naar main

Review-regels

Stel regels vast:

  • Minimaal 1 review vereist (beter: 2)
  • Tests moeten slagen
  • Code voldoet aan style guide
  • Geen eigen code reviewen

Geautomatiseerde checks

Zet geautomatiseerde checks in:

  • Linting: Code style controleren
  • Unit tests: Functionaliteit testen
  • Security scanning: Kwetsbaarheden detecteren
  • Code coverage: Testdekking meten

4. Documentatie

Goede documentatie is cruciaal voor hergebruik. Zonder documentatie blijft de beste code onbruikbaar.

Soorten documentatie

1. README.md (verplicht):

  • Wat doet deze software?
  • Voor wie is het bedoeld?
  • Hoe installeer je het?
  • Quick start voorbeeld
  • Licentie-informatie

2. Installatie-instructies:

  • Systeemvereisten
  • Stap-voor-stap installatie
  • Configuratie
  • Veelvoorkomende problemen

3. Gebruikersdocumentatie:

  • Functionaliteit uitgelegd
  • Screenshots/video’s
  • Use cases

4. Technische documentatie:

  • Architectuur-overzicht
  • API-documentatie
  • Database schema
  • Deployment-instructies

5. Bijdrage-richtlijnen (CONTRIBUTING.md):

  • Hoe bij te dragen?
  • Code style
  • Pull request proces
  • Testing vereisten

Documentatie-tools

  • Markdown bestanden: Simpel, in repository, versie-beheerd
  • GitHub/GitLab Wiki: Collaboratief, maar los van code
  • ReadTheDocs / MkDocs: Professionele documentatie-sites
  • Swagger / OpenAPI: Voor API-documentatie

Aanbeveling: Start met Markdown bestanden in /docs folder. Dat is laagdrempelig en werkt altijd.

5. Release management

Hoe breng je nieuwe versies uit? Release management zorgt voor duidelijkheid naar gebruikers.

Semantic Versioning

Gebruik semantic versioning (SemVer): MAJOR.MINOR.PATCH

  • MAJOR (1.0.0 → 2.0.0): Breaking changes, niet backwards compatible
  • MINOR (1.0.0 → 1.1.0): Nieuwe functionaliteit, backwards compatible
  • PATCH (1.0.0 → 1.0.1): Bug fixes, backwards compatible

Release proces

Eenvoudig proces:

  • Bepaal versienummer
  • Update CHANGELOG.md met wijzigingen
  • Tag de release in Git (v1.2.0)
  • Maak GitHub/GitLab release aan
  • Communiceer release naar gebruikers

CHANGELOG.md

Houd een changelog bij die per versie beschrijft:

  • Added: Nieuwe features
  • Changed: Wijzigingen in bestaande functionaliteit
  • Deprecated: Features die binnenkort verdwijnen
  • Removed: Verwijderde features
  • Fixed: Bug fixes
  • Security: Security fixes

Release cyclus

Bepaal een ritme:

  • Time-based: Elke 3 maanden een release
  • Feature-based: Release als belangrijke feature klaar is
  • Hybride: Vaste cyclus + ad-hoc voor urgent

Aanbeveling: Start met releases op basis van features. Als samenwerking mature wordt, ga naar vast ritme.

6. Issue tracking en projectbeheer

Hoe houd je bij wat er gedaan moet worden? Issues en projectborden helpen om overzicht te houden.

Issues

Gebruik issues voor:

  • Bug reports
  • Feature requests
  • Documentatie-verbeteringen
  • Vragen van gebruikers

Labels gebruiken:

  • Type: bug, feature, documentation, question
  • Prioriteit: critical, high, medium, low
  • Status: ready, in progress, blocked
  • good first issue: Voor nieuwe contributors

Issue templates

Maak templates voor verschillende soorten issues. Zorgt dat je altijd de juiste informatie krijgt.

Bug report template:

  • Wat verwachtte je?
  • Wat gebeurde er?
  • Stappen om te reproduceren
  • Versie / omgeving

Projectborden

GitHub Projects of GitLab Boards voor overzicht:

  • Backlog: Nog te doen
  • To Do: Gepland
  • In Progress: Wordt aan gewerkt
  • Review: Wacht op review
  • Done: Afgerond

Praktische tips

Begin simpel, bouw uit

Je hoeft niet alles vanaf dag 1 perfect te hebben. Start met: repository, README, LICENSE, en een simpele branch strategie. De rest groeit organisch.

Documentatie is geen one-time job

Documentatie raakt verouderd. Maak het onderdeel van je workflow: nieuwe feature → update documentatie.

Automatiseer wat je kunt

Zet CI/CD in voor testing, linting, en deployment. Dat scheelt handmatig werk en voorkomt fouten.

Investeer in onboarding

Maak het makkelijk voor nieuwe gemeenten of developers om te beginnen. Goede README + installatie-instructies betalen zich terug.

Leer van anderen

Kijk hoe andere succesvolle open source gemeenteprojecten het doen. Kopieer wat werkt.

Tip: Technische infrastructuur is geen doel op zich. Het moet samenwerken makkelijker maken. Als iets te complex wordt, vereenvoudig het.