Beheren van een repository

Met een repository binnen de organisatie wordt deze onderdeel van het NL Design System ecosysteem, waarop anderen kunnen vertrouwen en voortbouwen. Dit komt met een bepaalde verantwoordelijkheid en vraagt om actief onderhoud. Op deze pagina lichten we toe wat daarbij komt kijken.

Repositories sluiten aan op de NL Design System standaarden voor ontwikkeling, onderhoud en publicatie. Deze standaarden zijn gebaseerd op gangbare best practices en zijn bedoeld om onderhoud eenvoudiger te maken, samenwerking te verbeteren en de kwaliteit van onze software hoog te houden. Er is altijd ruimte voor uitzonderingen - sommige projecten hebben specifieke eisen waardoor een afwijkende inrichting logisch is. Aansluiten op de standaard is altijd het uitgangspunt. Zie je mogelijkheden om de standaard organisatiebreed te verbeteren? Dat moedigen we aan - bespreek het met de community, zodat iedereen ervan kan profiteren.

Geautomatiseerd build- en releaseproces

We verwachten dat repositories aansluiten op de standaard build- en releaseketen. We automatiseren zoveel mogelijk, voor transparantie in het proces en om de kans op fouten te minimaliseren.

Sluit aan op tooling zoals pnpm en TypeScript.
Implementeer een CI/CD pipeline die via de code in de repository zelf wordt beheerd; publiceren van packages gebeurt alleen via een CI/CD workflow. Gebruik bijvoorbeeld GitHub Actions, Forgejo Actions of GitLab Pipelines.
Changesets worden gebruikt om automatisch de changelog bij te werken.

Door packages of componenten te publiceren, kunnen anderen hiervan afhankelijk worden, en dat brengt verantwoordelijkheid met zich mee. Bij het publiceren van een package geldt daarom bovendien:

volg semantic versioning
gebruik deprecation wanneer functionaliteit wordt uitgefaseerd

Release early, release often: kleine, regelmatige releases zijn eenvoudiger te testen en reviewen (en eventueel terug te draaien) dan grote wijzigingen.

Transparantie en community

We verwachten dat maintainers bekende bugs zichtbaar maken, feature requests transparent beheren en duidelijk communiceren over breaking changes. Door gebruikers ook tijdig te informeren wanneer functionaliteit wordt uitgefaseerd zorgen we voor een voorspelbare upgrade-ervaring.

Organiseer een veilige werkomgeving door onze Code of Conduct zichtbaar te maken en toe te passen.

Vers & veilig houden van de repository en dependencies

Omdat software continu veroudert moeten dependencies periodiek worden gecontroleerd en bijgewerkt.

Van pnpm maken we gebruik van alle beveiligingsfunctionaliteit; onder andere pnpm audit
Dependabot wordt ingezet om automatisch PRs aan te maken. Controleer en merge deze regelmatig. Voor handmatige upgrades is npm-check-updates in te zetten.
Met zizmor auditen we de GitHub Actions workflows op veiligheid. Los bevindingen zo snel mogelijk op.

Door het onderhoud van dependencies als standaardwerkzaamheden te beschouwen voorkom je proactief technical debt. Door dezelfde tooling als de community te gebruiken kunnen upgrades vaak eenvoudig van andere repositories worden opgenomen.

Documentatie van componenten

Componenten worden white-label opgezet en alles wat nodig is om het component te implementeren en te gebruiken, wordt beschreven zodat gebruikers er optimaal mee aan de slag kunnen.

Documenteer de componenten in Storybook. Laat alle relevante varianten zien, beschrijf de publieke API (props) en geef richtlijnen voor het gebruik en de implementatie van het component.
Documentatie wordt online gepubliceerd (bijvoorbeeld via GitHub Pages of Vercel) zodat gebruikers altijd de meest recente versie kunnen raadplegen zonder de repository lokaal te hoeven starten.

Bewaak kwaliteit en volg conventies

Maak het eenvoudig om goede bijdragen te leveren en om kwaliteit vast te houden. Sluit aan op code conventies. Dit verlaagt de mentale overhead om jouw code te begrijpen.

Pas linting en formatting toe.
Gebruik Chromatic om visuele regressietests te doen. Hiermee worden onbedoelde visuele wijzigingen gedetecteerd voordat ze in een release terechtkomen.