Bijdragen aan de Nederlandse Richtlijn Digitale Systemen

Allereerst, bedankt dat je de tijd hebt genomen om een bijdrage te leveren! ❤️

We waarderen alle soorten bijdragen enorm. Zie die Inhoudsopgave voor verschillende manieren waarop je kan bijdragen aan de Nederlandse Richtlijn Digitale Systemen (NeRDS). Zorg ervoor dat je de relevante hoofdstukken even leest voordat je een bijdrage levert. Het zal het voor het team van de NeRDS een stuk makkelijker maken en de ervaring voor alle betrokkenen soepeler laten verlopen. We kijken uit naar alle bijdragen! 🎉

Opmerking

Het ontwikkelen van de NeRDS via GitHub is een bewuste keuze voor transparantie en samenwerking. We werken systematisch aan verschillende bouwblokken en prioriteren deze op basis van waarde en urgentie. Hierdoor kan het voorkomen dat reacties op suggesties of toevoegingen enige tijd vergen, vooral bij onderwerpen die later op de planning staan. We waarderen alle bijdragen en streven ernaar om feedback zo snel mogelijk te verwerken.

Inhoudsopgave

Code of Conduct

Dit project en iedereen die eraan deelneemt, valt onder de Code of Conduct. Door deel te nemen, wordt van je verwacht dat je je aan deze code houdt. Meld onacceptabel gedrag aan bureau.architectuur@minbzk.nl.

Ik heb een vraag

Maak een issue aan

Voordat je een Issues gaat aanmaken, kan je bekijken of jouw vraag al tussen de bestaande Issues staat. Wellicht staat er al een issue tussen die jou vraag kan beantwoorden.

Als je jouw vraag nog steeds wilt stellen, kan je een Issue aanmaken.

Gebruik daarvoor de knop new issue.
Formuleer je vraag of opmerking en geef een heldere toelichting.
Anderen kunnen nu opmerkingen toevoegen aan jouw issue.
Het team van de NeRDS zal deze issue labelen als question en pakt jouw issue zo snel mogelijk op. Mogelijk neemt het team van de NeRDS contact op voor een verduidelijking of een oplossing.

Stel een vraag via mail

Je kan je vragen ook altijd stellen door een mail te sturen naar bureau.architectuur@minbzk.nl.

Ik wil een fout of bug melden

Heb je een foutje gevonden in de NeRDS? Dan kan je deze melden door een Issue aan te maken.

Voordat je een Issues gaat aanmaken, kan je bekijken of jouw gevonden fout al tussen de bestaande Issues staat.

Als je de gevonden fout nog steeds wilt melden, kan je een Issue aanmaken.

Gebruik daarvoor de knop new issue.
Beschrijf de fout duidelijk en geef een heldere toelichting. Voeg waar mogelijk een screenshot toe.
Het team van de NeRDS zal deze issue labelen als bug en pakt jouw issue zo snel mogelijk op. Mogelijk neemt het team van de NeRDS contact op voor een verduidelijking of een oplossing.

Ik wil een verbetering voorstellen

Ter kennisgeving

Wanneer je bijdraagt aan dit project, moet je ermee akkoord gaan dat je 100% van de inhoud hebt geschreven, dat je de benodigde rechten op de inhoud hebt en dat de inhoud die je bijdraagt mag worden geleverd onder de Code of Conduct.

Heb je een suggestie of wil je een verbetering voorstellen? Dat kan gaan om een compleet nieuwe functionaliteit van de site of om kleine verbeteringen. Het volgen van onderstaande instructie helpt het team van de NeRDS om je suggestie te begrijpen en gerelateerde suggesties te vinden.

Je kan een suggestie doen door een Issue aan te maken of door een Pull Request te maken.

Voordat je een suggestie gaat maken

Voordat je een suggestie gaat maken, kan je bekijken of jouw suggestie al tussen de bestaande Issues staat. Wellicht bestaat er al een issue die jouw suggestie beschrijft, en zijn we er al mee bezig.
Zoek uit of jouw idee past binnen het doel en de scope van het project. Wat zijn de voordelen van deze functionaliteit of toevoeging? Het is aan jou om het team van de NeRDS en de community te overtuigen dat dit een nuttige toevoeging is aan de NeRDS. Houd in gedachten dat we functionaliteiten willen die nuttig zijn voor de meerderheid van onze gebruikers en niet slechts voor een kleine groep.

Een issue aanmaken

Als je jouw suggestie nog steeds wilt doen, kan je een Issue aanmaken.

Gebruik daarvoor de knop new issue.
Beschrijf duidelijk jouw suggestie en geef een heldere toelichting en onderbouwing waarom dit een goede toevoeging zal zijn aan de NeRDS
Het team van de NeRDS zal deze issue labelen als enhancement en pakt jouw issue zo snel mogelijk op. Mogelijk neemt het team van de NeRDS contact op voor een verduidelijking of een oplossing.

Afhankelijk van de complexiteit en het onderwerp van jouw suggestie kan het even duren voordat deze wordt opgepakt door het team van de NeRDS.

Een pull-request maken

Kun je niet uit de voeten met de issues? Bijvoorbeeld omdat je verschillende wijzigingsvoorstellen wilt doen? Je kan ook gebruik maken van een Fork en een Pull Request.

Stap-voor-stap pull request proces

Maak een fork van de repository
Clone je fork lokaal
Zet je ontwikkelomgeving op
Volg de stappen in Ontwikkelomgeving opzetten
Test of alles werkt met uv run mkdocs serve
Maak een nieuwe branch - Zie Branching strategie.
Maak je wijzigingen
Volg de Richtlijnen voor bijdragen
Test je wijzigingen lokaal
Controleer op spelfouten en broken links
Commit & push je wijzigingen naar de fork
Maak een pull request
Gebruik het pull request template
We maken gebruik van de tool pr-preview-action om automatisch previews te maken van een pull-request. Dit maakt het mogelijk om de wijzigingen die zijn gedaan in een pull-request al te bekijken in de uiteindelijke omgeving. Wanneer er een pull-request gedaan wordt via een fork, leidt dit helaas tot een error. Dit blokkeert de pull-request niet.
Er zijn ook andere manieren om een pull request te doen. Meer daarover.
Acceptatie criteria
Als de PR aan de voorwaarde voldoet, bekijkt het NeRDS team jouw aanpassingen en kan bij akkoord jouw aanpassingen mergen.

Hoe we werken op Github

We werken met Markdown bestanden. Dit is bestandsformaat voor platte tekstbestanden en wordt door veel verschillende tools ondersteund. Dit maakt het eenvoudig om versiebeheer op de NeRDS toe te passen.

Daarnaast maken gebruik van mkdocs en material for mkdocs om de informatie op een interactieve wijze inzichtelijk te maken op de website van de NeRDS.

Ontwikkelomgeving opzetten

Uitgebreide ontwikkelomgeving

Voor bijdragen aan de NeRDS heb je een lokale ontwikkelomgeving nodig:

Installeer dependencies

# Standaard versie (publiek toegankelijk)
uv pip install -r requirements.txt

# Of productie versie (MinBZK organisatie)
uv pip install -r requirements-prod.txt

Start de development server

uv run mkdocs serve

Bekijk je wijzigingen Open http://localhost:8000 in je browser

Wil je een nieuwe pagina aanmaken?

In het mkdocs.yml bestand staan de settings voor deze website. In richtlijn hoef je hier niets aan aan te passen, maar als je een nieuwe pagina wilt aanmaken kan het nodig zijn om hier een aanpassing in te doen. Onderdeel van deze settings is namelijk de navigatie voor de site (welke pagina's zijn zichtbaar, en welke pagina's vallen daaronder). Dit staat in de nav: sectie. Indien je een nieuwe pagina wilt toevoegen, is het vaak nodig deze wijziging ook door te voeren in het mkdocs.yml bestand.

Richtlijnen voor bijdragen

Inhoud schrijven

Taal: Schrijf in correct Nederlands
Tone of voice: Formeel maar toegankelijk, passend bij overheidsstandaarden
Structuur: Gebruik duidelijke kopjes en bullet points
Lengte: Houd artikelen beknopt en to-the-point
Bronnen: Verwijs naar officiële bronnen en standaarden waar relevant

Afbeeldingen en media

Plaats afbeeldingen in de juiste assets/ map
Gebruik beschrijvende bestandsnamen
Voeg altijd alt-tekst toe voor toegankelijkheid

Branching strategie

Gebruik kebab-case, houd de namen kort maar beschrijvend en vermijd speciale karakters. Branch types:

main: Productie-ready code
feat/beschrijving: Nieuwe functionaliteit
fix/beschrijving: Bug fixes
docs/beschrijving: Documentatie updates

Versioning

De NeRDS gebruikt automatische versioning voor releases:

Automatische patch versie bumps

Wanneer: Elke keer als een PR wordt gemerged naar main
Hoe: GitHub workflow triggert automatisch
Format: Volgt semantic versioning (major.minor.patch)
Wat gebeurt er: Patch versie wordt automatisch verhoogd

Versioning schema

major.minor.patch

Major (x.0.0): Grote veranderingen of herstructureringen
Minor (0.x.0): Nieuwe functionaliteiten en inhoud toevoegingen
Patch (0.0.x): Bug fixes en kleine verbeteringen (automatisch)

Voor contributors

Als contributor hoef je je geen zorgen te maken over versioning:

Patch versies worden automatisch verhoogd bij elke merge
Major en minor versies worden handmatig beheerd door het NeRDS team
Focus op duidelijke commit messages en PR beschrijvingen
Het team bepaalt of wijzigingen een minor of major versie vereisen

Tip: Door duidelijke commit messages te schrijven help je het team om te bepalen of een wijziging een minor versie bump verdient in plaats van alleen een patch.