docs: CONTRIBUTING.md part 1

Author: tomootes

CONTRIBUTING.md

@@ -0,0 +1,250 @@
+# bijdragerichtlijnen
+
+> _Voor het maken van een eigen CONTRIBUTING raadpleeg [ons artikel over CONTRIBUTING.md](https://developer.overheid.nl/kennisbank/algemeen/open-source/standaarden/contributing-md)_
+
+## Introductie
+
+Om te beginnen, hartelijk dank voor je interesse om bij te dragen aan een gezamenlijke Developer Portal voor de hele Nederlandse overheid! Door onze ervaringen te delen, helpen we anderen om beter onderbouwde keuzes te maken. Omdat wij willen voorkomen dat we standaarden of projecten uit specifieke organisaties een voorkeursbehandeling geven, ontvangen we graag thema's en documentatie van zoveel mogelijk organisaties binnen de overheid.
+
+Software bouwen voor de overheid brengt specifieke uitdagingen met zich mee. Deze portal helpt je om te voldoen aan overheidspecifieke eisen, zoals securitystandaarden en toegankelijkheidsrichtlijnen. Daarnaast vind je hier informatie over beschikbare Open Source-projecten en hoe je deze kunt inzetten.
+
+## Hoe je kunt bijdragen
+
+Alle artikelen in onze kennisbank zijn geschreven in de `.md` of `.mdx` extensie en dus eenvoudig aan te passen.
+
+- Door een onderwerp/ standaard aan te dragen waarover wij zouden moeten schrijven op onze kennisbank. Je doet dit door een [issue in te schieten](https://github.com/developer-overheid-nl/don-site/issues/new).
+- Door zelf een artikel bij te dragen. Je doet dit door een [fork te maken](https://github.com/developer-overheid-nl/don-site/fork) en deze vervolgens aan te bieden als [pull request](https://github.com/developer-overheid-nl/don-site/compare).
+- Door een API [toe te voegen](https://apis.developer.overheid.nl/apis/toevoegen) aan ons API register.
+- Door een git organisatieaccount [toe te voegen](https://oss.developer.overheid.nl/toevoegen/repository) aan ons OSS register.
+- Door vragen te stellen of je te mengen in discussies in ons [Slack kanaal](https://codefornl.slack.com/archives/CFV4B3XE2).
+- Bugs te melden. Je doet dit door een [issue in te schieten](https://github.com/developer-overheid-nl/don-site/issues/new).
+- Ideeën aan te dragen om ons design, UX of accessibility te verbeteren. Je doet dit door een [issue in te schieten](https://github.com/developer-overheid-nl/don-site/issues/new).
+
+Door deze richtlijnen te volgen, communiceer je dat je de tijd respecteert van de ontwikkelaars die
+dit open source-project beheren en ontwikkelen. In ruil daarvoor moeten ze dat respect beantwoorden
+bij het aanpakken van uw melding, het beoordelen van wijzigingen en het helpen afronden van uw pull
+requests.
+
+Houd een open geest! Het verbeteren van documentatie, melden van fouten, of bijdragen aandragen zijn
+voorbeelden van nuttige bijdragen. Veel informatie is mogelijk al ergens beschikbaar, waarschijnlijk
+in het Engels, en het verwijzen naar andere documentatie helpt ons allemaal. Helemaal als daar
+samenvattingen (of volledige) vertalingen van in het Nederlands toegevoegd worden (daar of in dit
+project)!
+
+Mochten bijdragen niet voldoen aan deze richtlijnen dan houden wij ons de vrijheid om commentaren te
+negeren en bijdragen te sluiten. Daarbij zullen wij verwijzen naar deze richtlijnen / Contributing
+Guide.
+
+> En als je het project leuk vindt, maar gewoon geen tijd hebt om bij te dragen, is dat prima. Er
+> zijn andere eenvoudige manieren om het project te steunen en je waardering te tonen, waar we ook
+> erg blij mee zijn:
+>
+> - Geef het project een ster
+> - Tweet erover
+> - Verwijs naar dit project in de readme van uw project
+> - Noem het project op lokale meetups en vertel het aan je vrienden/collega's
+
+## Basis regels
+
+### Gedragscode
+
+Dit project en iedereen die eraan deelneemt, wordt bestuurd door de [OSPO-NL
+Gedragscode](CODE_OF_CONDUCT.md). Door deel te nemen, wordt van u verwacht dat u zich aan deze code
+houdt. Gelieve onaanvaardbaar gedrag te melden volgens de
+[Gedragscode#Handhaving](CODE_OF_CONDUCT.md#handhaving).
+
+### Verwachtingen
+
+Vrijwel alle content is beschreven in Markdown. Daarbij maken wij gebruik van MkDocs Material om
+alle documentatie te publiceren. Bij gebruik van plaatjes is het fijn als de bron daarvan ook
+onderdeel is van dit project ... en bij voorkeur in een open formaat. Dat betekent dat deze
+aangepast en bijgewerkt kunnen worden zonder kosten te maken voor tools. Nogmaals: bij voorkeur.
+
+- Zorg dat bijdragen cross-platform uitwisselbaar zijn: Windows, Mac, Linux.
+- Zorg dat code en documentatie compleet is en voldoet aan de [styleguides](#styleguides).
+- Maak issues aan voor elke grote wijziging en verbetering die je graag wilt maken. Bespreek de
+  dingen transparant en vraag community feedback.
+- Probeer bijdragen compact en klein te houden; dat draagt bij aan het behoud van overzicht en
+  wijzigingen.
+- Wees open naar nieuwe mensen en moedig nieuwe bijdragen aan van alle achtergronden.
+- Issues behoren van een passend label te zijn voorzien:
+  - `Bug` betekent een urgent probleem in de community of in de documentatie
+  - `Enhancement` betekent een bijdrage voor uitbreiding
+  - `Question` betekent een vraag
+
+## Ik heb een vraag
+
+> Als je een vraag wilt stellen, gaan we ervan uit dat je de beschikbare
+> [documentatie](https://ospo-nl.github.io/kennisbank/) hebt gelezen.
+
+Voordat je een vraag stelt, kun je het beste zoeken naar bestaande
+[issues](https://github.com/ospo-nl/kennisbank/issues) die je kunnen helpen. Als u een geschikt
+probleem hebt gevonden en nog steeds verduidelijking nodig heeft, kunt u uw vraag in dit nummer
+schrijven. Het is ook raadzaam om eerst op internet naar antwoorden te zoeken.
+
+Als je dan toch de behoefte voelt om een vraag te stellen en verduidelijking nodig hebt, raden we
+het volgende aan:
+
+- Open een [issue](https://github.com/ospo-nl/kennisbank/issues/new).
+- Geef het issue een passend label (zie [verwachtingen](#verwachtingen)).
+- Geef zoveel mogelijk context over waar je tegenaan loopt.
+- Indien van toepassing: Lever technische afhankelijkheden die relevant lijken.
+
+We zullen het probleem dan zo snel mogelijk in behandeling nemen.
+
+## Ik wil bijdragen
+
+> **Juridische mededeling**
+>
+> Wanneer u bijdraagt aan dit project, moet u ermee instemmen dat u 100% van de inhoud hebt
+> geschreven, dat u over de benodigde rechten op de inhoud beschikt en dat de inhoud die u bijdraagt
+> onder de projectlicentie mag worden geleverd.
+
+### Issues melden
+
+#### Voordat u een issue indient
+
+Een goed issue zou er niet voor moeten zorgen dat anderen u moeten achtervolgen voor meer
+informatie. Daarom vragen we u om dit zorgvuldig te onderzoeken, informatie te verzamelen en het
+probleem in detail te beschrijven in uw melding.
+
+- Zorg ervoor dat u de nieuwste versie gebruikt.
+- Lees de [documentatie](https://ospo-nl.github.io/kennisbank/) aandachtig door en ontdek of de
+  functionaliteit al wordt gedekt, misschien door een individuele configuratie.
+- Voer een [zoekopdracht](https://github.com/ospo-nl/kennisbank/issues) uit om te zien of de
+  verbetering al is voorgesteld. Als dit het geval is, voeg dan een opmerking toe aan de bestaande
+  uitgave in plaats van een nieuwe te openen.
+
+Voor dit moment is er alleen documentatie en zijn verdere voorbereidingen niet nodig. Mocht er ooit
+tools en software componenten opgeleverd worden, dan is het van belang om de details daarvan ook
+duidelijk te melden en te onderzoeken of het daadwerkelijk een probleem met die software is of dat
+het wellicht toch een fout in uw omgeving is.
+
+#### Hoe dien ik een goed issue in?
+
+> U mag beveiligingsgerelateerde problemen, kwetsbaarheden of issues, inclusief gevoelige
+> informatie, nooit melden aan de issue tracker of elders in het openbaar. In plaats daarvan moeten
+> gevoelige bugs per e-mail naar <TODO> worden gestuurd.
+
+We gebruiken GitHub-problemen om issue en fouten op te sporen. Als u een probleem met het project
+tegenkomt:
+
+- Open een [issue](https://github.com/ospo-nl/kennisbank/issues/new). (Omdat we op dit moment niet
+  zeker weten of het een fout is of niet, vragen we je om nog niet over een fout te praten en het
+  probleem niet te labelen.)
+- Leg zo duidelijk mogelijk uit wat u verwacht of wens en geef suggesties voor invulling daarvan.
+- Geef de informatie op die u in het vorige gedeelte hebt verzameld.
+
+Zodra het is ingediend:
+
+- Het projectteam zal het probleem dienovereenkomstig labelen.
+- Een teamlid zal proberen het issue te begrijpen en op te volgen.
+
+#### Meer hulp
+
+Hier zijn een paar vriendelijke (maar Engelse) handleidingen voor meer hulp en achtergronden: [First
+Timers Only](http://www.firsttimersonly.com/) en [Make A Pull Request](http://makeapullrequest.com/)
+
+### Verbeteringen voorstellen
+
+Deze sectie begeleidt u bij het indienen van een verbeteringssuggestie voor OSPO-NL, **inclusief
+volledig nieuwe functies en kleine verbeteringen aan bestaande functionaliteit**. Door deze
+richtlijnen te volgen, kunnen beheerders en de community uw suggestie begrijpen en gerelateerde
+suggesties vinden.
+
+#### Voordat u een verbetering indient
+
+- Zorg ervoor dat u de nieuwste versie gebruikt.
+- Lees de [documentatie](https://ospo-nl.github.io/kennisbank/) aandachtig door en ontdek of de
+  functionaliteit al wordt gedekt, misschien door een individuele configuratie.
+- Voer een [zoekopdracht](https://github.com/ospo-nl/kennisbank/issues) uit om te zien of de
+  verbetering al is voorgesteld. Als dit het geval is, voeg dan een opmerking toe aan de bestaande
+  uitgave in plaats van een nieuwe te openen.
+- Ga na of uw idee past binnen de reikwijdte en doelstellingen van het project. Het is aan u om een
+  sterk pleidooi te houden om de ontwikkelaars van het project te overtuigen van de voordelen van
+  deze functie. Houd er rekening mee dat we functies willen die nuttig zijn voor de meerderheid van
+  onze gebruikers en niet slechts voor een kleine subgroep. Als u zich slechts op een minderheid van
+  gebruikers richt, overweeg dan om een bibliotheek met add-ons/plug-ins te schrijven.
+
+#### Hoe dien ik een goede verbeteringssuggestie in?
+
+Suggesties voor verbeteringen worden bijgehouden als [GitHub
+issues](https://github.com/ospo-nl/kennisbank/issues).
+
+- Gebruik een **duidelijke en beschrijvende titel** voor het probleem om de suggestie te
+  identificeren.
+- Geef een stapsgewijze beschrijving van de voorgestelde verbetering met zoveel mogelijk details.
+- Beschrijf het huidige gedrag en leg uit welk gedrag je in plaats daarvan verwachtte te zien en
+  waarom. Op dit punt kunt u ook zien welke alternatieven niet voor u werken.
+- Misschien wilt u schermafbeeldingen en geanimeerde GIF's toevoegen die u helpen de stappen te
+  demonstreren of aan te geven op welk onderdeel de suggestie betrekking heeft. U kunt deze tool
+  gebruiken om GIF's op macOS en Windows op te nemen, en deze tool of deze tool op Linux.
+- Leg uit waarom deze verbetering nuttig zou zijn voor de meeste gebruikers van OSPO-NL. Misschien
+  wil je ook wijzen op de andere projecten die het beter hebben opgelost en die als inspiratie
+  kunnen dienen.
+
+## Review proces
+
+Om wijzigingen goed te kunnen beheren, volgen en uit te leggen, volgen we een eenvoudig proces van
+review en Pull Requests (PRs).
+
+- Wijzigingen wordt nooit direct op de `main` branch gedaan, maar altijd in een 'feature' branch.
+- Maak een Pull Request aan zodra je klaar bent. Of maak gelijk een Draft Pull Request aan nadat u
+  uw feature branch hebt aangemaakt. Zodra uw wijzigingen klaar zijn voor review, wijzigt u uw Draft
+  PR naar 'Ready for Review'.
+- Een teamlid reviewt de wijzigingen in het Pull Request en geeft commentaar en/of goedkeuring
+  (Approve).
+- Na goedkeuring kan het Pull Request gemerged worden. Hiervoor wordt standaard 'Squash & Merge'
+  gebruikt. In geval dat de PR door een teamlid is ingediend, reviewt een ander teamlid de PR maar
+  wordt de merge overgelaten aan de auteur van de PR.
+- Na de merge dienen bijbehorende issues bijgewerkt te worden zodat deze niet onnodig open blijven
+  staan ofwel beantwoord worden.
+
+## Styleguides
+
+### Markdown
+
+Alle documentatie moet 'machine-readable' zijn en tegelijk ook makkelijk leesbaar en onderhoudbaar
+voor mensen. Daarom maken we gebruik van **Markdown**. Zie ook [GitHub
+Markdown](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax)
+en de algemene [Markdown handleiding](https://www.markdownguide.org/basic-syntax/) (EN) (of zelfs de
+originele [documentatie](https://daringfireball.net/projects/markdown/syntax)). De documentatie van
+het gebruikte [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/reference/) thema
+benoemt de opmaak die extra wordt ondersteunt door het thema.
+
+Alinea's worden op of binnen **100 karakters** afgekapt om versiebeheer per regel beheersbaar te
+maken. Dit kan automatisch worden afgedwongen in tooling, bijv. [Rewrap in
+VSCode](https://stkb.github.io/Rewrap/) (keyboard shortcut: `alt+Q`).
+
+### Bestandsnamen
+
+Alle bestandsnamen, zowel van bestanden (files) als van mappen (folders), komen terug in de URL van
+de gepubliceerde documentatie ... en spaties zijn niet zo standaard voor URLs. Daarom worden er GEEN
+spaties gebruikt in bestandsnamen. Deze worden vervangen door `_`, underscores. In het genereren van
+de documentatie worden deze netjes vervangen door spaties zodat de layout er wel mooi en netjes uit
+ziet! :muscle:
+
+### Regeleinden
+Er zijn meerdere manieren om regeleinden (Engels: line endings) te codificeren in bestanden. Voor
+dit project horen die `LF` te zijn, zoals gebruikelijk voor de meeste projecten. Hiermee is
+gegarandeerd dat op Linux, Windows en Mac OSX bestanden op dezelfde wijze worden gepresenteerd en
+Pull Requests gemakkelijk zijn. Lokaal uitchecken met CRLF (in Windows) en commits met LF is
+uiteraard toegestaan .. als het resultaat maar met LF in GitHub terecht komt :smile:
+
+Zie ook [Blog: Mind the End of Your
+Line](https://adaptivepatchwork.com/2012/03/01/mind-the-end-of-your-line/) en [GitHub Help on Line
+Endings](https://docs.github.com/en/get-started/getting-started-with-git/configuring-git-to-handle-line-endings).
+
+## Community
+
+De OSPO-NL Community is nog in oprichting. Voor dit moment zijn er nog geen officiële kanalen en
+samenwerkingsverbanden anders dan actief betrokken personen. Zie ook meer in de [over
+ons](https://ospo-nl.github.io/kennisbank/Over_ons).
+
+## Attribution
+
+Een eigen CONTRIBUTING maken is niet echt moeilijk ... en toch ook weer wel. Inspiratie voor deze
+variant komt van een
+[template](https://github.com/nayafia/contributing-template/blob/HEAD/CONTRIBUTING-template.md) en
+**contributing-gen**. [Genereer zelf](https://github.com/bttger/contributing-gen) (incl. CODE OF
+CONDUCT) !